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.

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

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

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

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

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

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

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

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)

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.