writing

Route writing tasks to the correct artifact structure. Classify first, then write.

Artifact Types

Docs Impact

Classify scope before writing:

• Customer-facing: user-visible behavior, API usage, config surfaces, deployment/runtime
• Internal: engineering workflow, architecture contracts, contributor guidance, runbooks
• Both: when both audiences are affected
• None: record explicit skip rationale

Workflow

1. Classify — identify artifact type and docs impact lane before writing.
2. Structure first — lay out headings and sections matching the artifact type, then fill.
3. Write concretely — specific over vague, examples over descriptions, scannable over dense.
4. Verify completeness — check required sections exist for the artifact type.

Changelog Rules

• Breaking changes: lead with **BREAKING:**, state what fails if users do nothing, provide migration steps.
• What's New: write user-facing outcomes ("Now supports..."), not internal refactors.
• Deprecations: announce before removing, provide replacements and timelines.
• Fixes: describe user impact ("X now works"), skip internal noise.

Anti-Patterns

• Starting to write without classifying the artifact type
• Mixing Diataxis modes in a single section (tutorial steps inside a reference page)
• Walls of text without headings or scannable structure
• Documenting implementation details instead of user-facing behavior
• Changelog entries that describe code changes instead of user impact