documentation-review
Comprehensive checklist and process for reviewing documentation qualityincluding voice, tone, structure, completeness, and technical accuracy.
When & Why to Use This Skill
This Claude skill provides a comprehensive framework for auditing and improving the quality of technical documentation. It systematically evaluates content across five critical dimensions—voice and tone, structure, completeness, clarity, and technical accuracy—ensuring that API references, manuals, and guides meet professional standards and maintain style guide consistency.
Use Cases
- Pre-publication quality assurance: Reviewing draft API documentation to ensure all parameters, error codes, and JSON examples are technically accurate and complete.
- Documentation auditing: Evaluating existing knowledge base articles to identify and fix passive voice, inconsistent terminology, or outdated structural hierarchies.
- Style guide compliance: Automatically checking technical tutorials against specific writing standards, such as using active voice and sentence-case headings.
- Clarity and readability enhancement: Identifying overly complex sentences or undefined jargon in technical whitepapers to improve accessibility for non-expert users.
| name | ring:documentation-review |
|---|---|
| description | | |
| trigger | | |
| skip_when | | |
| after | [writing-functional-docs, writing-api-docs] |
| complementary | [voice-and-tone, documentation-structure] |
Documentation Review Process
Review documentation systematically across multiple dimensions. A thorough review catches issues before they reach users.
Review Dimensions
- Voice and Tone – Does it sound right?
- Structure – Is it organized effectively?
- Completeness – Is everything covered?
- Clarity – Is it easy to understand?
- Technical Accuracy – Is it correct?
Voice and Tone Review
| Check | Flag If |
|---|---|
| Second person | "Users can..." instead of "You can..." |
| Present tense | "will return" instead of "returns" |
| Active voice | "is returned by the API" instead of "The API returns" |
| Tone | Arrogant ("Obviously...") or condescending |
Structure Review
| Check | Flag If |
|---|---|
| Hierarchy | Deep nesting (H4+), unclear parent-child |
| Headings | Title Case instead of sentence case |
| Section dividers | Missing --- between major topics |
| Navigation | Missing links to related content |
Completeness Review
Conceptual docs: Definition, characteristics, how it works, related concepts, next steps
How-to guides: Prerequisites, all steps, verification, troubleshooting, next steps
API docs: HTTP method/path, all parameters, all fields, required vs optional, examples, error codes
Clarity Review
| Check | Flag If |
|---|---|
| Sentence length | >25 words per sentence |
| Paragraph length | >3 sentences per paragraph |
| Jargon | Technical terms not explained on first use |
| Examples | Abstract data ("foo", "bar") instead of realistic |
Technical Accuracy Review
Conceptual: Facts correct, behavior matches description, links work
API docs: Paths correct, methods correct, field names match API, types accurate, examples valid JSON
Code examples: Compiles/runs, output matches description, no syntax errors
Common Issues to Flag
| Category | Issue | Fix |
|---|---|---|
| Voice | Third person ("Users can...") | "You can..." |
| Voice | Passive ("...is returned") | "...returns" |
| Voice | Future tense ("will provide") | "provides" |
| Structure | Title case heading | Sentence case |
| Structure | Wall of text | Add --- dividers |
| Completeness | Missing prereqs | Add prerequisites |
| Completeness | No examples | Add code examples |
| Clarity | Long sentences (40+ words) | Split into multiple |
| Clarity | Undefined jargon | Define on first use |
Review Output Format
Note: Documentation reviews use
PASS/NEEDS_REVISION/MAJOR_ISSUESverdicts (graduated), which differ from code review verdicts (PASS/FAIL/NEEDS_DISCUSSION).
## Review Summary
**Overall Assessment:** [PASS | NEEDS_REVISION | MAJOR_ISSUES]
### Issues Found
#### High Priority
1. **Line 45:** Passive voice "is created by" → "creates"
#### Medium Priority
1. **Line 23:** Title case in heading → sentence case
#### Low Priority
1. **Line 12:** Could add example for clarity
### Recommendations
1. Fix passive voice instances (3 found)
2. Add missing API field documentation
Quick Review Checklist
Voice (30s): "You" not "users", present tense, active voice
Structure (30s): Sentence case headings, section dividers, scannable (bullets/tables)
Completeness (1m): Examples present, links work, next steps included
Accuracy (varies): Technical facts correct, code examples work