Documentation Engineering

Purpose

Code tells you how. Documentation tells you why and what. We treat documentation as an engineering artifact: structured, versioned, and maintained.

When to Use This Skill

• New Project: "Write a README."
• Knowledge Transfer: "Explain how this works."
• API: "Document this endpoint."
• Handover: "Create a user guide."

Core Framework: Diátaxis

Classify your document into one of four quadrants to ensure clarity.

1. Tutorials (Learning-oriented): A lesson to get a beginner started.

- Example: "Build your first Todo App in 5 minutes." - Tone: Inspiring, step-by-step, no choices (follow me).

1. How-to Guides (Problem-oriented): A recipe to solve a specific problem.

- Example: "How to reset your password." - Tone: Practical, concise, steps 1-2-3.

1. Reference (Information-oriented): Technical description of machinery.

- Example: "User API Class Specification." - Tone: Dry, accurate, complete.

1. Explanation (Understanding-oriented): Context and background.

- Example: "Why we chose Rust over C++." - Tone: Discursive, theoretical.

Google Style Guide Highlights

• Voice: Active, not passive. ("Click the button", not "The button should be clicked").
• Second Person: Speak to "you" (the user).
• Simplicity: Use short sentences and plain language.

Resource Files