微信扫一扫Route writing tasks to correct artifact structure. Classify first, then write.
Artifact Types
| Artifact | Key structure | |----------|--------------| | Docs (public/internal) | Diataxis: one mode per section — tutorial, how-to, reference, or explanation. Never mix. | | Changelog / release notes | User-facing impact grouped by type (added, changed, fixed, removed) | | README | Purpose → quick start → usage → contributing; scannable, no walls of text | | Runbook | Trigger → steps → verification → rollback; executable by someone unfamiliar |
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: both audiences affected
- None: record explicit skip rationale
Workflow
- Classify — artifact type and docs impact lane before writing.
- Structure first — headings and sections matching artifact type, then fill.
- Write concretely — for human-facing prose (including chat summaries, status reports, and questions written back to the user), follow
references/prose-quality.md. Every how-to includes a runnable example; every reference section uses consistent field table. - Verify completeness — required sections exist for artifact type.
Changelog Rules
- Breaking changes: lead with
**BREAKING:**, state what fails if users do nothing, provide migration steps. - What's New: user-facing outcomes ("Now supports..."), not internal refactors.
- Deprecations: announce before removing, provide replacements and timelines.
- Fixes: user impact ("X now works"), skip internal noise.
Anti-Patterns
- Writing without classifying artifact type
- Mixing Diataxis modes in a single section (tutorial steps inside reference page)
- Changelog entries describing code changes instead of user impact