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