Documentation Quality Review
Assess whether documentation is well-written, consistent, and appropriate for its audience. The output is a scored review with specific findings — not rewrites.
When to Use
- Before releases — ensure docs meet a quality bar
- During doc review — structured alternative to "looks good to me"
- When users report docs are confusing, inconsistent, or too technical
- After bulk doc generation — verify machine-written docs read naturally
- Periodic quality check on documentation health
Quick Reference
| Resource | Purpose | Load when |
|---|---|---|
references/quality-dimensions.md | Scoring rubrics for each dimension | Always (Phase 1) |
references/style-checklist.md | Concrete style rules for common issues | Phase 2 (review pass) |
Workflow Overview
Phase 1: Scope → Identify docs to review and their intended audience
Phase 2: Review → Score each doc across quality dimensions
Phase 3: Synthesize → Aggregate findings, identify patterns
Phase 4: Report → Produce the scored quality reviewPhase 1: Scope the Review
Before reviewing, establish context:
- Identify the docs — which files or sections are in scope?
- Identify the audience — who reads these docs? (new user, experienced developer, operator, contributor)
- Identify the doc type — reference, tutorial, guide, explanation, or README?
- Load the rubrics — read
references/quality-dimensions.mdto calibrate scoring
The audience and doc type determine which dimensions matter most. A reference page has different quality criteria than a tutorial.
Phase 2: Review Each Document
Score each document across five dimensions. Read the full document before scoring.
Dimension 1: Readability
How easily can the target audience read and understand this?
| Score | Criteria |
|---|---|
| 5 | Clear, concise prose. Short paragraphs. Active voice. Appropriate vocabulary for audience |
| 4 | Generally clear. Minor instances of passive voice, long sentences, or unnecessary jargon |
| 3 | Readable but effortful. Multiple long paragraphs, some jargon without definition, occasional ambiguity |
| 2 | Difficult. Dense prose, heavy jargon, passive constructions, unclear antecedents |
| 1 | Impenetrable. Wall of text, undefined terms, ambiguous instructions, no structure |
What to check:
- Sentence length — flag sentences over 30 words
- Paragraph length — flag paragraphs over 6 sentences
- Passive voice density — flag sections where >40% of sentences are passive
- Jargon — flag technical terms used without definition on first occurrence
- Ambiguous pronouns — "it", "this", "that" without clear referent
- Nominalizations — "perform an installation" instead of "install"
Dimension 2: Consistency
Does this doc use the same terms, formatting, and conventions throughout — and match the rest of the doc set?
| Score | Criteria |
|---|---|
| 5 | Consistent terminology, formatting, heading style, code block conventions, and tone throughout |
| 4 | Minor inconsistencies (e.g., "config" vs "configuration" in different sections) |
| 3 | Noticeable inconsistencies across sections but each section is internally consistent |
| 2 | Frequent inconsistencies in terminology, formatting, or conventions |
| 1 | No discernible consistency — reads like it was written by different people at different times |
What to check:
- Term alignment — same concept should use the same word everywhere
- Heading hierarchy — consistent use of
##vs###, capitalization style - Code block formatting — language tags present, consistent indentation
- List formatting — bullet vs number, punctuation, capitalization
- Admonition/callout style — consistent use of note/warning/tip conventions
- Tense — consistent within a doc type (imperative for instructions, present for descriptions)
Dimension 3: Audience Fit
Is the content calibrated to the right level for its intended readers?
| Score | Criteria |
|---|---|
| 5 | Perfectly pitched. Prerequisites stated. Appropriate depth. No unexplained leaps |
| 4 | Mostly well-calibrated. Occasional assumption of knowledge not established |
| 3 | Uneven. Some sections too basic, others too advanced. Prerequisites unclear |
| 2 | Significant mismatch. Beginner docs assume expert knowledge, or expert docs over-explain basics |
| 1 | Wrong audience entirely. Content pitched at a different reader than intended |
What to check:
- Prerequisite assumptions — what must the reader already know?
- Explanation depth — does it match the audience's expected background?
- Context gaps — would a new reader understand *why*, not just *what*?
- Leaps — does the doc jump from basic to advanced without transition?
- Condescension — does it over-explain things the audience already knows?
Dimension 4: Structure & Scannability
Can a reader find what they need without reading linearly?
| Score | Criteria |
|---|---|
| 5 | Logical heading hierarchy. Scannable sections. Tables for reference data. Clear entry points |
| 4 | Good structure. Minor issues with heading granularity or section ordering |
| 3 | Adequate structure but some sections are too long or headers don't reflect content |
| 2 | Poor structure. Key information buried in prose. Headings misleading or inconsistent |
| 1 | No useful structure. Single long section with no headings, or headings that don't help navigation |
What to check:
- Heading hierarchy — does it create a useful outline?
- Front-loading — are key facts early in each section, or buried at the end?
- Tables vs prose — is reference data in tables or hidden in paragraphs?
- Section length — flag sections over 500 words without a subheading
- TL;DR — do long docs have a summary or overview section?
Dimension 5: Actionability
Can the reader *do something* after reading? (Weighted differently by doc type.)
| Score | Criteria |
|---|---|
| 5 | Clear next steps. Commands are copy-pasteable. Examples are complete and runnable |
| 4 | Mostly actionable. Minor gaps in examples or steps |
| 3 | Partially actionable. Some instructions unclear or missing context |
| 2 | Weakly actionable. Reader knows *about* the topic but not *how* to apply it |
| 1 | Not actionable. Pure description with no path to action |
What to check:
- Code examples — do they work if copy-pasted? Are imports included?
- Commands — are they complete with required flags and paths?
- Steps — are they sequential and numbered? Any missing steps?
- Expected output — does the doc show what success looks like?
- Error guidance — if something goes wrong, does the doc say what to do?
Dimension Weighting by Doc Type
| Dimension | Reference | Tutorial | Guide | Explanation | README |
|---|---|---|---|---|---|
| Readability | 1.0 | 1.2 | 1.2 | 1.3 | 1.2 |
| Consistency | 1.2 | 0.8 | 1.0 | 0.8 | 1.0 |
| Audience Fit | 0.8 | 1.3 | 1.2 | 1.2 | 1.3 |
| Structure | 1.3 | 1.0 | 1.0 | 0.8 | 1.0 |
| Actionability | 1.0 | 1.5 | 1.3 | 0.5 | 1.0 |
Phase 3: Synthesize Findings
After scoring individual docs, look for patterns:
- Systemic issues — same problem across many docs (e.g., inconsistent terminology everywhere)
- Outliers — one doc much better or worse than the rest
- Audience mismatches — docs in the wrong section for their actual audience
- Style drift — sections written at different times with different conventions
Systemic issues are more valuable to fix than individual ones — fixing the pattern fixes many docs at once.
Phase 4: Produce the Quality Review
Report Format
# Documentation Quality Review
**Review date:** YYYY-MM-DD
**Scope:** [files or sections reviewed]
**Target audience:** [who these docs serve]
**Doc type:** [reference / tutorial / guide / explanation / mixed]
---
## Summary
[2-3 sentences: overall quality assessment]
Overall scores (weighted):
| Dimension | Raw Score | Weight | Weighted |
|-----------|-----------|--------|----------|
| Readability | N/5 | Nx | N |
| Consistency | N/5 | Nx | N |
| Audience Fit | N/5 | Nx | N |
| Structure | N/5 | Nx | N |
| Actionability | N/5 | Nx | N |
| **Total** | | | **N / 25** |
Quality grade: [A (22-25) / B (18-21) / C (14-17) / D (10-13) / F (<10)]
---
## Findings
### Critical (must fix before publish)
| # | File | Dimension | Issue | Fix |
|---|------|-----------|-------|-----|
| 1 | [path:line] | [dimension] | [specific problem] | [specific fix] |
### Major (should fix)
| # | File | Dimension | Issue | Fix |
|---|------|-----------|-------|-----|
### Minor (nice to fix)
| # | File | Dimension | Issue | Suggestion |
|---|------|-----------|-------|------------|
---
## Systemic Issues
### [Issue pattern name]
**Affected docs:** [list]
**Dimension:** [which]
**Pattern:** [what's happening across docs]
**Recommended fix:** [one-time fix that addresses all instances]
---
## Per-Document Scores
| Document | Read. | Cons. | Aud. | Struct. | Action. | Weighted Total |
|----------|-------|-------|------|---------|---------|----------------|
| [path] | N | N | N | N | N | N |
---
## Strengths
[What's working well — cite specific examples worth emulating]Integration with Other Doc Skills
doc-maintenance → Structural health (links, orphans, folders)
doc-claim-validator → Semantic accuracy (do claims match code?)
doc-completeness-audit → Topic coverage (is everything documented?)
doc-quality-review → Prose quality (is it well-written?)
doc-architecture-review → Information architecture (is it findable?)Anti-Patterns
- Do not rewrite docs during the review — produce findings, not rewrites
- Do not score without reading the full document — skimming misses context
- Do not apply tutorial standards to reference docs or vice versa — use the weighting table
- Do not penalize technical precision as "jargon" in docs for technical audiences
- Do not flag style preferences as quality issues — "I'd phrase it differently" is not a finding
- Do not review generated API docs (JSDoc, Sphinx auto) — review the source comments instead
- Do not score docs in
docs/archive/— they are historical
Bundled Resources
References
references/quality-dimensions.md— Detailed scoring rubrics with examples for each score levelreferences/style-checklist.md— Concrete style rules for the most common quality issues