Documentation Review System
Mode-routed documentation review that diagnoses a page against its doc type and seven quality dimensions before touching a sentence, then picks the intervention level — maintenance, improve, rewrite, author, or strategy — that actually matches what's wrong.
"Review this doc" usually gets you either a pile of comma fixes on a page whose structure is fundamentally broken, or a rewrite nobody asked for on a page that just needed a cleanup pass — because nothing forced a diagnosis before the edits started.
Who it's for: technical writers standardizing review quality across a docs team, engineers who own docs alongside code and want a repeatable process, developer-relations teams auditing an existing docs site, anyone whose "can you review this doc" requests currently get inconsistent, mood-dependent results
Example
"Review this troubleshooting page" → A doc-type classification (troubleshooting, with a buried task-shaped section flagged as secondary), a diagnosis against seven quality dimensions surfacing that the page buries its actual fix three paragraphs in, an intervention-level call of rewrite rather than line edits, and a restructured page with house style applied last and validation run to confirm
New here? 3-minute setup guide → | Already set up? Copy the template below.
# Documentation Review System
A mode-routed process for reviewing, improving, rewriting, authoring, or planning documentation. Diagnoses a page against its doc type and a fixed set of quality dimensions before touching a single sentence, then chooses an intervention level that actually matches what's wrong — instead of defaulting to line edits on a page whose real problem is its shape.
## When to Use
- Asked to review, improve, rewrite, or author a documentation page
- Asked for advice on page structure, doc type, audience, or content strategy
- Asked to fix formatting, style, or compliance issues in docs
## Use a Light Touch When
- The request is a trivial grammar or typo fix that doesn't need full diagnosis
- The page is already structurally sound and only needs minor editorial cleanup
## Workflow
Follow this sequence for every request. Steps 1–4 are diagnosis; steps 5–7 are action.
### 1. Determine the Requested Outcome
Read the request and map it to a mode:
| Request Pattern | Mode |
|---|---|
| "Fix links, callouts, formatting" | `maintenance` |
| "Make this clearer", "improve this page" | `improve` |
| "This doc is a mess; rewrite it" | `rewrite` |
| "Draft docs for feature X" | `author` |
| "What kind of page should this be?" | `strategy` |
| "Review this doc" (unspecified) | **hybrid** — see below |
**Hybrid behavior** for vague asks like "review this doc":
- If the draft is obviously weak or the ask implies planning → critique-first (lead with diagnosis).
- If the page is decent and the ask implies cleanup → improve-first (lead with edits).
**Default:** when ambiguous, default to `improve`, not `maintenance` — most "review this" requests want more than formatting fixes.
### 2. Determine the Primary Doc Type
Classify the page:
- **concept** — explains what something is and why it matters
- **task** — walks the reader through accomplishing a goal
- **reference** — lookup for options, API, or config
- **troubleshooting** — diagnose and fix a problem
- **migration** — move from one version or approach to another
- **decision guide** — choose between options
Always select **one** primary type, even if the page contains secondary elements. After selecting it, identify any **secondary sections** — sections with their own heading whose content follows a different doc type's shape (a `task` page with an embedded `troubleshooting` sidebar, say). Note these for Step 3.
### 3. Diagnose the Draft
Evaluate the page against these quality dimensions, in order:
1. **Intent clarity** — does the page know what job it's doing?
2. **Audience fit** — is it pitched at the right reader (first-timer vs. expert)?
3. **Information shape** — does its structure match its doc type?
4. **Conceptual clarity** — are the underlying ideas actually explained, or just named?
5. **Task usability** — can a reader actually follow it and succeed?
6. **Example quality** — are examples concrete, correct, and representative?
7. **Economy** — is anything here padding, throat-clearing, or redundant with another page?
For secondary sections, evaluate dimensions 3 (Information Shape) and 5 (Task Usability) against the secondary section's *own* doc type, not the page's primary type. All other dimensions apply page-wide.
If the page shows signs of structural weakness, check it against these common antipatterns:
- **Mixed-type sprawl** — a page trying to be a concept doc, a task guide, and a reference all at once, with no section doing any one job cleanly.
- **Buried lede** — the actual point arrives three sections in, after throat-clearing the reader has to wade through.
- **Reference-as-narrative** — lookup content (a table's worth of options) forced into paragraph prose instead of a table or list.
- **Task-as-concept** — a how-to page that explains theory at length before ever telling the reader what to actually do.
- **Orphaned example** — a code sample or walkthrough with no surrounding explanation of when or why to use it.
- **Split-brain page** — content that serves two audiences (a beginner and an API consumer, say) with neither served well.
### 4. Choose the Intervention Level
Use these thresholds:
- No structural issues, minor style problems → `maintenance`
- Structure is okay but framing, order, or examples are weak → `improve`
- Structure is wrong for the page's job → `rewrite`
- Page doesn't exist yet → `author`
- User wants advice, not edits → `strategy`
**Hard rule:** when the draft is structurally weak, don't stop at sentence-level edits. Reorder, split, replace examples, or rewrite the page's shape.
**Split/escalation rule:** if the dominant job is unclear, or the page serves multiple unrelated jobs, switch to `strategy` mode or recommend a page split before polishing. A well-structured secondary section is not, by itself, a reason to split the page.
### 5. Improve or Plan
Execute based on the chosen mode:
- **`maintenance`** — apply editorial and compliance fixes only.
- **`improve`** — strengthen framing, order, explanation, and examples; keep the page's identity.
- **`rewrite`** — materially replace the page; preserve sound content, discard or restructure the rest.
- **`author`** — write the page from scratch using the primary doc type's shape as a guide.
- **`strategy`** — return a planning artifact, not an edited page:
- Audience
- Page job
- Primary doc type
- Recommended outline
- Split/merge recommendation (if applicable)
- Preserve list (content worth keeping)
Do not edit files or run any validation in `strategy` mode.
### 6. Apply House Style
For edit modes (`maintenance`, `improve`, `rewrite`, `author`), apply the project's actual style guide last — voice, tone, heading conventions, link formatting, component usage, frontmatter rules. This step is always downstream of structural and editorial work, never the first pass: fixing style on a structurally broken page wastes the pass.
### 7. Validate
For edit modes only, run whatever validation the project actually has (a docs linter, a build check, a link checker). Fix any errors reported, then run it again to confirm. Skip this step entirely in `strategy` mode or when no files were edited.
## Tips
- The hybrid-mode judgment call in Step 1 is worth getting right — leading with a wall of critique on a page the user just wants lightly cleaned up reads as pedantic, and leading with quiet edits on a page that's structurally broken buries the real problem.
- Don't let a well-written secondary section talk you out of noticing the page's primary type is wrong. A gorgeous troubleshooting sidebar doesn't fix a concept page that never explains the concept.
- When diagnosing Economy (dimension 7), actively check for content that duplicates another page rather than only judging the page in isolation.
## Limitations
- Assumes the page (or planned page) sits in a real docs tree with an identifiable audience and doc type — this doesn't help much with marketing copy or free-form long-form writing.
- Validation in Step 7 is a placeholder for whatever tooling the project actually has; wire it to the project's real linter/build check rather than skipping it.
- Designed for single-page reviews. A full docs-site information-architecture pass (which pages should exist at all) is a `strategy`-mode judgment call, not something this workflow automates end-to-end.
Get new playbooks like this one
One email a week with new Claude Code workflows. Free, like everything here.
No spam. Unsubscribe anytime.
What This Does
Routes every documentation request — review, improve, rewrite, author, or "just give me advice" — through a diagnosis pass before any edit happens. It classifies the page's primary doc type (concept, task, reference, troubleshooting, migration, or decision guide), evaluates it against seven quality dimensions in a fixed order (intent clarity, audience fit, information shape, conceptual clarity, task usability, example quality, economy), and only then picks an intervention level: light maintenance, a strengthening pass, a full rewrite, ground-up authoring, or a planning artifact with no files touched.
The hard rule underneath it: when a page's structure is genuinely wrong for its job, sentence-level polish doesn't fix it — reorder, split, replace examples, or rewrite the shape. House style (voice, headings, link conventions) is always the last pass, applied after structure and content are right, never the first move.
Quick Start
Step 1: Create a Project Folder
mkdir docs-review && cd docs-review
Step 2: Download the Template
Click Download above, then:
mv ~/Downloads/CLAUDE.md ./
Step 3: Review a Page
claude
Then paste in the doc you want reviewed, or say "review this page" and point at the file. Claude will classify its doc type, diagnose it, and tell you which intervention level applies before making any changes.
Tips & Best Practices
- The hybrid-mode call for a vague "review this doc" request matters: lead with critique when the draft is obviously weak, lead with edits when it's decent and just needs cleanup. Getting this backwards reads as either pedantic or evasive.
- Don't let a well-written secondary section talk you out of flagging that the page's primary type is wrong — a gorgeous troubleshooting sidebar doesn't fix a concept page that never explains the concept.
- Check the Economy dimension against the rest of the docs tree, not just the page in isolation — padding that duplicates another page is still padding.
Limitations
- Assumes a real docs tree with an identifiable audience and doc type per page — less useful for marketing copy or free-form long-form writing.
- The validation step (Step 7) is a placeholder for whatever the project's own docs tooling is — wire it to a real linter or build check rather than skipping it.
- Built for single-page reviews; a full site-wide information-architecture pass is better treated as its own
strategy-mode exercise, not automated end-to-end here.