doc-refine — Technical Documentation Reading Experience Optimization Guide
Review vs. Rewrite Boundaries
First, distinguish between review and rewrite: when only a review is requested, provide issues and suggestions; when a rewrite is explicitly requested, only modify authorized documents. If changes involve behavior or facts rather than expression adjustments, preserve the original intent and point out parts requiring confirmation.
Protect before trimming: Technical behaviors, API/data contracts, preconditions and boundary conditions, security and legal warnings, accessibility alternative descriptions, valid examples, source links, and stable anchors. Code already having the same behavior is not sufficient evidence that documentation can be deleted; locally necessary repetition can aid independent reading.
Two Inspection Goals
All judgments ultimately reduce to two questions:
| Axiom | Question to Ask Yourself | In One Sentence |
|---|---|---|
| ① Quick Find | Can the target reader determine where information is from the table of contents and headings? | Clear Signposts |
| ② Every Paragraph Has a Purpose | Would deleting it lose information needed to complete a task, understand behavior, or control risk? | Complete and Concise |
Apply these two checks to every piece of content. If ① is not met → change headings, add diagrams, adjust structure. If ② is not met → cross-check protected items and reader tasks, then suggest merging or trimming; do not delete necessary content just to reduce length.
Workflow
1. Diagnose (Read the Full Document First, Don't Rush to Edit)
Read through the target document, recording issues per section:
- Does the heading convey content independently of numbering? (No → Axiom ① violation)
- Does the same logic/rule appear in 2+ places? (Yes → Axiom ② violation)
- Does this behavioral description help users understand contracts, constraints, or outcomes? Judge purpose first; don't mechanically delete based on "what/why."
- Is the lead-in only repetitive padding? Can be trimmed, but retain step orientation, warnings, or limitations.
- Are 3+ items being compared scattered in prose? (Yes → Use a table)
- Is a diagram easier to understand for flows or states than text? Choose Mermaid or keep text based on the target renderer's capability.
- Does the example address real confusion, error recovery, or edge cases? Keep examples valid for the target reader.
2. Fix (Apply Changes Categorized by Axiom)
See specific rules below in §Axiom ① and §Axiom ②.
3. Verify (Quantitative Baseline)
After fixing, read the Checklist as needed to check information completeness and reading effectiveness. Not every metric must be met—they are diagnostic tools, not laws; exceptions are allowed when clarity takes precedence.
Axiom ①: Quick Find
Heading Discernibility
Headings are signposts. When maintainers scan the TOC, they should immediately know what each section contains.
Judgment Criteria: If you need to click into the section to know what it's about, the heading is too vague.
| ❌ Too Vague | ✅ Discernible | Why Changed |
|---|---|---|
5.1 Table-level | 5.1 Project CRUD (Table-level Endpoints) | "Table-level" could be anything |
5.3 Row-level | 5.3 Row-level Collaboration Endpoints | Reader knows there are operations like claiming/delivering here |
5.4 Export | 5.4 Full CSV Export | What format? Full or partial? |
Endpoints | HTTP Endpoints | Remove ambiguity |
Tip: When core concepts are too short, add qualifiers in parentheses for key information. But don't overdo it— the goal is to convey "what's in this section" in ≤15 characters, not write a paper title.
Information Architecture
- One job per section: Organize content by the primary reader task (tutorial, how-to, reference, explanation); necessary API signatures or brief context can be kept, long materials use cross-references.
- Core first, details later: Place the most important information at the beginning of a section or document top (Progressive Disclosure). Advanced/edge-case information can be collapsed or in appendices.
- Self-sufficiency principle: Maintainers should be able to start reading from any page without "prior knowledge" (Every Page is Page One). When prerequisite concepts are needed, state them at the top of the section and add links.
Diagram Alt Text
Use diagrams when relationships, sequences, or comparisons are clearer with visual aids; retain searchable text and necessary alternative descriptions.
Decision Tree:
What is the information type?
├─ Multi-step process / branching decisions → Flowchart
├─ Event-driven state changes → State diagram (stateDiagram-v2)
├─ 3+ items × 2+ dimensions to compare → Table
├─ Component relationships / architecture layers → Diagram + layers
├─ Definitions / context / precise values → Text (default)
└─ Uncertain → Default to text (diagrams are enhancements, not decorations)
Mermaid Best Practices:
- Nodes ≤30—beyond that, layout algorithms become unreadable; split into overview+detail multiple diagrams
- Add labels to branch conditions and unclear relationships; clear sequential arrows may not need labels to avoid label noise
- Use
subgraphto group related nodes TD(top-down) works for hierarchies;LR(left-to-right) works for sequences/pipelines
Table Design (Tufte Principles):
- Remove unnecessary lines, shadings, pure decoration—"Above all else show the data"
- Minimal effective difference: visual distinctions as subtle as possible but clear
- Align numbers by column for easy scanning and comparison
- Always keep text horizontal; prohibit vertical text
Axiom ②: Every Paragraph Has a Purpose
Deduplication
Having the same information in multiple places is the #1 enemy of maintainability—change one, forget the other.
Detection Criteria (Hit any → needs deduplication):
- The same logic/rule appears in 2+ sections → keep the authoritative source (usually the data model or state machine section), change the rest to cross-references
- After checking behavior, preconditions, risks, and independent reading, a paragraph has no information loss → merge or trim
- Documentation repeats implementation details → judge if the reader needs it; keep behavioral descriptions and contracts; do not delete because code already has it
- Multiple equivalent approaches → give a default recommendation; keep necessary alternatives that differ in compatibility, permissions, or usage conditions
ARID ≠ DRY: Documentation accepts necessary repetition—restating reference concepts in tutorials is reasonable. But eliminate parallel maintenance: the same fact should not be maintained independently in two places, or one will inevitably be outdated.
Simplify
Cut everything that does not serve the current needs of the reader.
| Bad Smell | Fix | Why |
|---|---|---|
| Repetitive lead-in: "In this section we will discuss…" | Merge into direct statement | Keep necessary step orientation |
| Filler words: "It should be noted that" / "It is worth mentioning that" | Trim guide phrases | Warnings or limitations themselves must still be retained |
| Heavy passive voice ("is used for…" "will be…") | Change to active SVO | Shorter, clearer, reader knows "who is doing what" |
| Synonym drift (same function with different words) | Unify terminology, one word one meaning | Clearly inform the reader of the function's name |
| Hard-to-read long nested sentences | Break into logical sentences | Don't break relationships between conditions, exceptions, and conclusions |
| Listing equivalent options | Recommended option first, necessary alternatives after | Retain feasible choices under different constraints |
Example Restraint
Examples are the strongest quick-answer tool, but also the most easily abused content type. Write the Docs specifically says "Include (some) examples"—the "some" in parentheses is a deliberate limit.
When to Use Examples:
- Readers need quick answers and will jump directly to examples (first reaction for many)
- Concepts are hard to understand without concrete examples
- Demonstrating high-frequency, real-world use cases
When NOT to Use Examples:
- Demonstrating the obvious (Microsoft: "Don't illustrate obvious points")
- Artificial scenarios that don't aid understanding; synthetic examples that are clearly marked and verifiable can be kept
- Adding just for "completeness" without real user need driving it
- Too many examples already—adding more reduces scannability
Good Examples:
- Cover only the most common use cases, not exhaustive
- Self-contained and runnable (copy-paste to work)
- Progress from simple to complex
- Show expected output so readers can verify
- Omit boilerplate only when the example still runs or preconditions are clearly stated; retain necessary imports, error handling, and expected output
Bad Examples:
- Demonstrating the obvious
- Unrealistic artificial scenarios
- One example tries to cover too many variables
- Error handling unrelated to the example is stuffed in
- Claimed runnable code not verified; clearly mark verification limits when it cannot run
Position Rules:
- Simple one-line examples → inline in body
- Longer examples → separated from dense reference material (standalone paragraphs or collapsible sections)
- Examples in reference documentation → remain restrained, only for usage illustration, not mixed with teaching
Quantitative Baseline Quick Reference
The following are only initial screening prompts adjusted per language and audience; see Checklist for details.
| Dimension | Suggested Starting Point | Usage Boundary |
|---|---|---|
| English sentence length | Watch for nesting around 20 words | Do not mechanically apply to Chinese; do not break conditions and contracts |
| Paragraph | One main point per paragraph | Exceptions and warnings can stay with the original paragraph |
| List/steps | Consider grouping when long | Do not delete complete steps just to reduce item count |
| Passive voice | Rewrite when subject is unclear | Set no mandatory proportion |
| Mermaid | Consider overview and details when nodes are many | Judge by actual render readability |
| Table | Consider splitting or transposing for wide tables | Keep necessary columns and units for comparison |
Numbers are suggestions, not industry pass/fail standards or research laws; do not alter facts, contracts, safety, or legal texts to meet them.
Anti-Pattern Quick Reference
| Anti-Pattern | Symptom | Solution |
|---|---|---|
| Almighty Thud | Mega-document, all information equal weight, key decisions buried | Split or add priority levels |
| Type Mixing | API reference stuffed into tutorial, reference contains "why" | Separate by Diátaxis |
| Repetitive Lead-in | Introductory sentences with no substantive information | Trim wording, keep risk and step information |
| Synonym Drift | Same function called by different words | Unify terminology |
| Unclear Relationships | Branch or arrow meaning requires guessing | Add labels to unclear relationships |
| Chartjunk | Tables with unnecessary decorative lines, shading | Remove non-informative decoration |
| Example Overload | Examples exhausting all scenarios | Keep only most common use cases |
| Parallel Maintenance | Same fact maintained independently in multiple places | Keep one, change the rest to links |