docs-write skill

---
name: docs-write
description: "Write or update documentation (tutorial, how-to, reference, explanation) with clear style, structure, visuals, API/ADR/runbook patterns. Use when: (1) Creating or updating docs after code changes, (2) During PR preparation or addressing review feedback, (3) Adding new features that need documentation, (4) Updating API endpoints, database schemas, or configuration, (5) Creating ADRs or runbooks, (6) Adding or updating diagrams and visual documentation, (7) When documentation needs to be written or revised, (8) For tutorial creation, how-to guides, or technical writing, or (9) For documentation standards compliance and structure. Triggers: write docs, update documentation, create documentation, write tutorial, document API, write ADR, create runbook, add documentation, document this, write how-to."
metadata:
  author: ai-dev-atelier
  version: "1.0"
---

# 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.