nickcrew/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