ringdocumentation-review
Comprehensive checklist and process for reviewing documentation quality including voice, tone, structure, completeness, and technical accuracy.
安装与使用
请根据来源仓库和你的 AI 工具说明安装此技能。先阅读技能文件和依赖要求，再添加到工作流。
查看来源 ↗使用指南技能说明
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
使用示例
查看来源仓库中的使用示例与配置说明。
查看来源 ↗来源历史
- 收录时间
- 2026-01-20
- 索引更新时间
- 2026-02-03
- Branch
- main
收录与同步日期属于本站记录。源码修改历史请查看来源仓库。
GitHub ↗chat Comments (0)
Sign in to join the discussion and leave a comment.
No comments yet. Be the first to share your thoughts!