Doc Writing

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).
2. 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.
3. Reference (Information-oriented): Technical description of machinery.
   • Example: "User API Class Specification."
   • Tone: Dry, accurate, complete.
4. 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