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_ISSUES verdicts (graduated), which differ from code review verdicts (PASS/FAIL/NEEDS_DISCUSSION ).
Review Summary
Overall Assessment: [PASS | NEEDS_REVISION | MAJOR_ISSUES]
Issues Found
High Priority
- Line 45: Passive voice "is created by" → "creates"
Medium Priority
- Line 23: Title case in heading → sentence case
Low Priority
- Line 12: Could add example for clarity
Recommendations
- Fix passive voice instances (3 found)
- 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
Standards Loading (MANDATORY)
Before reviewing documentation:
-
Load voice and tone - ring:voice-and-tone for style verification
-
Load structure patterns - ring:documentation-structure for organization checks
-
Load document type patterns - ring:writing-functional-docs or ring:writing-api-docs
HARD GATE: CANNOT review documentation without loading relevant standards.
Blocker Criteria - STOP and Report
Condition Decision Action
Style guide unavailable STOP Report: "Need style guide to review against"
Source material missing STOP Report: "Need source to verify technical accuracy"
Review scope undefined STOP Report: "Need to know what aspects to review"
Technical SME unavailable STOP Report: "Need SME access for accuracy verification"
Cannot Be Overridden
These requirements are NON-NEGOTIABLE:
-
MUST review all five dimensions (voice, structure, completeness, clarity, accuracy)
-
MUST flag all issues found (not just major ones)
-
MUST provide specific line references for issues
-
MUST categorize issues by priority (High/Medium/Low)
-
CANNOT approve documentation with HIGH-priority issues
-
CANNOT skip accuracy verification
Severity Calibration
Severity Criteria Examples
CRITICAL Factually incorrect, misleading information Wrong API paths, incorrect behavior described
HIGH Major voice/structure violations, missing sections Passive voice throughout, no examples
MEDIUM Multiple minor issues, inconsistencies Mixed pronouns, some title case
LOW Polish issues, optimization opportunities Could flow better, minor wording
Pressure Resistance
User Says Your Response
"Just do a quick review, we're rushing" "Quick review still covers all 5 dimensions. CANNOT skip any review category."
"Only check for typos" "Review MUST cover voice, structure, completeness, clarity, AND accuracy. Typos are LOW priority."
"Skip technical accuracy, trust the writer" "Technical accuracy MUST be verified. Trust but verify."
"Approve it, minor issues can be fixed later" "CANNOT approve with HIGH priority issues. They must be fixed first."
"The content is more important than style" "Style affects comprehension. Voice and tone are REQUIRED review dimensions."
Anti-Rationalization Table
Rationalization Why It's WRONG Required Action
"Good enough for now" Good enough ≠ meets standards MUST flag all issues
"Writer knows the product" Knowledge ≠ documentation quality Review all dimensions
"Style issues are subjective" Style guidelines are objective standards Apply guidelines consistently
"Users won't notice minor issues" Minor issues accumulate into poor UX Flag all issues regardless of size
"Review is blocking release" Poor docs also block user success Complete review properly
"Trust the automated checks" Automated checks miss context Human review is REQUIRED
When This Skill is Not Needed
Signs that documentation doesn't need review:
-
Documentation was written by ring-tw-team specialists
-
Previous review found zero issues
-
Documentation hasn't changed since last review
-
All five review dimensions already verified
If all above are true: Review may be skipped for unchanged content.
Note: New or modified documentation MUST always be reviewed.