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/personas.md	Six concrete reader personas with quality signals	Always (Phase 1)
references/quality-dimensions.md	Doc-type-aware 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 (with persona discovery)

Before reviewing, establish context. Persona discovery is foundational — without it, scoring applies a generic standard that systematically misjudges docs whose audience differs from default. A reference doc that serves API Looker-Up reads as "too terse" against a generic readability rubric; against the right persona, that terseness is the goal.

1. Identify the docs — which files or sections are in scope?
2. Identify the doc type per file — reference, tutorial, guide, explanation, ADR, runbook, or README. (Use the type → default persona mapping in references/personas.md.)
3. Identify the personas — which 1–3 personas from references/personas.md are the primary readers per doc? When the doc type strongly suggests a persona, prefer that default unless the doc itself shows evidence of a different audience.
4. Note conflicts — when one doc legitimately serves multiple personas with different needs (e.g., a CLI reference serves both API Looker-Up and Operator), capture this. Per-persona scoring surfaces conflicts in the report.
5. Load the rubrics — references/quality-dimensions.md is now doc-type-aware. Each dimension has different 5/5 criteria per type.