Docs Write

Quick Checklist

• Audience and doc type (tutorial/how-to/reference/explanation)
• Clear style, active voice, consistent terms
• Structure: headings, skimmable, examples first
• Include visuals when helpful (mermaid inline; puml when reused)
• API: auth, requests/responses, errors, breaking changes
• ADR/runbook: context, decision/steps, rollback, contacts
• Cross-links and filenames; run docs-check after edits

Workflow

Writing Documentation

IMPORTANT: Before writing documentation, read references/documentation-guide.md to understand all standards, patterns, and requirements. Do not make assumptions about documentation style, structure, or content – always reference the guide for specific details.

1. Read the full guide first: Load references/documentation-guide.md to understand complete documentation standards

   • This ensures you have all context about style, structure, doc types, and examples
   • Do not proceed with writing until the guide is loaded in context

2. Determine doc type: Read references/documentation-guide.md section “Doc Types (Divio)” to choose tutorial, how-to, reference, or explanation

   • Tutorial: Learning-oriented, step-by-step for beginners
   • How-to: Goal-oriented, task-focused
   • Reference: Fact-oriented, API/technical details
   • Explanation: Understanding-oriented, concepts and context

3. Review style guidelines: Read references/documentation-guide.md sections:

   • “Style and Voice” – Active voice, clear language, consistent terminology
   • “Structure and Skimmability” – Headings, examples first, clear organization
   • Reference the guide for exact formatting, terminology, and style requirements

4. Draft content: Use the checklist above, include code examples, and follow the structure guidelines from the guide

5. Add visuals if needed: Read references/documentation-guide.md section “Visuals and Diagrams”

   • Use Mermaid for inline diagrams (ER diagrams, sequence diagrams)
   • Use PlantUML (.puml files) for diagrams referenced from multiple docs
   • See examples in the guide for exact syntax – do not guess
   • Use look_at to interpret screenshots or diagrams before documenting
   • Use ui_to_artifact for a starter code snippet from a mockup

6. For API documentation: Read references/documentation-guide.md section “API Documentation”

   • Document authentication, request/response formats, error codes
   • Include examples for all endpoints (see guide for format)
   • Document breaking changes prominently

7. For ADRs/Runbooks: Read references/documentation-guide.md section “ADRs and Runbooks”

   • ADRs: Context, decision, consequences
   • Runbooks: Steps, rollback procedures, contacts
   • Follow exact templates from the guide

8. Review and finalize: Read references/documentation-guide.md section “Templates and Checklists”

   • Verify all checklist items are addressed
   • Add cross-references to related documentation
   • Ensure consistent terminology (check guide for exact terms)

9. Verify: Run bash skills/docs-check/scripts/check-docs.sh to ensure documentation is complete

Reference Files

REQUIRED: Always read references/documentation-guide.md before writing documentation. The guide contains all standards, examples, and requirements. Do not make assumptions – load the guide and reference specific sections.

Read these sections from references/documentation-guide.md as needed:

• Style and Voice (#style-and-voice) – Writing style, active voice, terminology
• Structure and Skimmability (#structure-and-skimmability) – Organization, headings, examples
• Doc Types (Divio) (#doc-types-divio) – Tutorial, how-to, reference, explanation types
• API Documentation (#api-documentation) – API docs patterns, examples, error handling
• ADRs and Runbooks (#adrs-and-runbooks) – Decision records and operational procedures
• Visuals and Diagrams (#visuals-and-diagrams) – Mermaid and PlantUML usage
• Templates and Checklists (#templates-and-checklists) – Documentation checklists
• When to Document (#when-to-document) – What changes require documentation

Full guide: references/documentation-guide.md – Complete documentation standards and best practices

Integration with Other Skills

• Use after ada::docs:check flags required updates.
• Combine with ada::code-review outcomes to address documentation feedback.
• Run ada::code-quality after docs updates if code touched.

Examples

• New feature: choose how-to; add overview, steps, examples, and links; add diagram if complex.
• API change: document auth, requests/responses, errors, breaking changes; link to workflows.
• Schema change: update schema doc and ER diagram; link from API/feature docs if impacted.