doc-quality-review

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 review

---

Phase 1: Scope the Review

Before reviewing, establish context:

1. Identify the docs — which files or sections are in scope?
2. Identify the audience — who reads these docs? (new user, experienced developer, operator, contributor)
3. Identify the doc type — reference, tutorial, guide, explanation, or README?
4. Load the rubrics — read references/quality-dimensions.md to 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 level
• references/style-checklist.md — Concrete style rules for the most common quality issues