| name | writing-documentation |
| description | Best practices for project documentation including README, CONTRIBUTING, CHANGELOG, and Markdown files. Use when updating documentation, writing README sections, or maintaining project docs. |
| allowed-tools | Read, Grep, Glob |
Standards for creating and maintaining clear, consistent project documentation.
Core Philosophy
Documentation should be scannable, actionable, and maintainable. Every section must justify its existence. Verbose documentation is rarely read.
File Standards
README.md
Essential sections (in order): Title/Description, Installation, Usage, Configuration (if applicable), License
Avoid: Lengthy introductions, obvious explanations, feature lists duplicating code, purposeless badges
CONTRIBUTING.md
Essential sections: Development Setup, Code Standards, Testing, Pull Request Process
CHANGELOG.md
Follow Keep a Changelog format. Newest first. Group by: Added, Changed, Deprecated, Removed, Fixed, Security.
Markdown Standards
| Element | Rule |
|---|
| Headers | One H1 per file, hierarchical (no skipping), no punctuation |
| Code blocks | Always specify language |
| Lists | Use - for unordered, 1. for ordered, parallel grammar |
| Links | Descriptive text (not "click here"), relative for internal docs |
Writing Style
- Active voice: "Run npm install" not "Dependencies can be installed by running..."
- Imperative mood: "Install the package" not "You should install the package"
- Cut filler: Delete "In order to", "It is important to note that", "This section will explain"
- One idea per sentence
Code Examples
Make examples runnable: complete (not fragments), realistic variable names, show expected output when helpful.
Configuration Docs
Show examples with inline comments, not verbose prose descriptions.
Common Issues
Outdated instructions, missing prerequisites, broken examples, inconsistent formatting, stale information
