Documentation Writing

Doc Writing/Audit Workflow

Doc writing/audit progress:
- [ ] Step 1: Determine doc type (tutorial, how-to, reference, explanation) and audience
- [ ] Step 2: Run CRITICAL checks (voice and tone, structure and organization)
- [ ] Step 3: Run HIGH checks (clarity and language, code examples)
- [ ] Step 4: Run MEDIUM+ checks for remaining categories in scope
- [ ] Step 5: Report findings with file:line and concrete fixes

1. Audit only changed files unless a full sweep is requested.
2. Identify the doc type (tutorial, how-to, reference, explanation) and intended audience to select relevant categories.
3. Load rule files progressively by category prefix — read only what applies.
4. Prioritize CRITICAL and HIGH findings before medium-priority polish.
5. After fixes, rerun the relevant rules before finalizing.

Rule Categories by Priority

voice-

structure-

clarity-

code-

format-

nav-

scan-

hygiene-

review-

Quick Reference

• Category map and impact rationale:

  rules/_sections.md

• Rule-level guidance and examples:

  rules/<prefix>-*.md

rules/voice-defaults.md
rules/structure-diataxis.md
rules/clarity-defaults.md

• Why the rule matters
• Incorrect example
• Correct example

Review Output Contract

## Documentation Audit Findings

### path/to/file.md
- [CRITICAL] `voice-defaults`: Passive voice obscures who performs the action.
  - Fix: Rewrite "The configuration is loaded by the server" as "The server loads the configuration."

### path/to/clean-file.md
- ✓ pass

• Group findings by file.
• Use

  file:line

  when line numbers are available.
• State issue and propose a concrete fix.
• Include clean files as

  ✓ pass

  .