| name | write-good-docs |
| description | Write, review, and restructure useful documentation with Diataxis, audience-specific README patterns, and AI-writing trope cleanup. Use when creating docs, improving READMEs, reorganizing documentation, or editing prose for clarity. |
Write Good Docs
Use this skill when documentation needs to become more useful, not merely longer.
Layout
Reading Order
Do not read the whole skill directory by default.
- Classify the documentation task.
- Load only the relevant reference area below.
- Write or edit the docs.
- Run the AI-writing trope check before finalizing prose.
Task Router
Writing or reorganizing documentation
Start with Diataxis:
Then read the page-type reference that matches the job:
Use the boundary references when content is mixed:
Creating or improving a README
Read:
Choose the template that matches the audience:
Editing prose that sounds machine-generated
Read:
Diataxis Compass
Use this table to classify docs:
| If the content... | ...and serves the user's... | ...then it belongs in... |
|---|
| informs action | acquisition of skill | a tutorial |
| informs action | application of skill | a how-to guide |
| informs cognition | application of skill | reference |
| informs cognition | acquisition of skill | explanation |
Ask:
- Is this about doing something or knowing something?
- Is the user learning or working?
Defaults
- One page should have one primary job.
- Tutorials teach by doing; they are safe, concrete, and teacher-led.
- How-to guides help a competent user complete a real task.
- Reference describes machinery accurately and tersely.
- Explanation develops understanding, context, and tradeoffs.
- READMEs answer the audience's first real questions.
- Prose should be specific, direct, and varied enough to avoid obvious AI-writing patterns.
Sources
