---
name: documentation-review
description: |
  Comprehensive checklist and process for reviewing documentation quality
  including voice, tone, structure, completeness, and technical accuracy.

trigger: |
  - Reviewing draft documentation
  - Pre-publication quality check
  - Documentation audit
  - Ensuring style guide compliance

skip_when: |
  - Writing new documentation → use writing-functional-docs or writing-api-docs
  - Only checking voice → use voice-and-tone

sequence:
  after: [writing-functional-docs, writing-api-docs]

related:
  complementary: [voice-and-tone, documentation-structure]
---

# Documentation Review Process

Review documentation systematically across multiple dimensions. A thorough review catches issues before they reach users.

---

## Review Dimensions

Documentation review covers five key areas:

1. **Voice and Tone** – Does it sound right?
2. **Structure** – Is it organized effectively?
3. **Completeness** – Is everything covered?
4. **Clarity** – Is it easy to understand?
5. **Technical Accuracy** – Is it correct?

---

## Voice and Tone Review

### Check Second Person Usage
- [ ] Uses "you" instead of "users" or "one"
- [ ] Addresses reader directly
- [ ] Creates connection with the audience

**Flag:**
> ❌ "Users can create accounts..."
>
> ✅ "You can create accounts..."

### Check Tense
- [ ] Uses present tense for current behavior
- [ ] Uses future tense only for planned features
- [ ] Avoids conditional ("would", "could") when stating facts

**Flag:**
> ❌ "The API will return a response..."
>
> ✅ "The API returns a response..."

### Check Active Voice
- [ ] Subject performs the action
- [ ] Avoids passive constructions
- [ ] Clear who/what is doing what

**Flag:**
> ❌ "An error is returned by the API..."
>
> ✅ "The API returns an error..."

### Check Tone
- [ ] Assertive but not arrogant
- [ ] Encouraging, not condescending
- [ ] Technical but human
- [ ] Sounds like helping a colleague

---

## Structure Review

### Check Hierarchy
- [ ] Logical content organization
- [ ] Clear parent-child relationships
- [ ] Appropriate nesting depth (max 3 levels)

### Check Headings
- [ ] Uses sentence case (not Title Case)
- [ ] Action-oriented where appropriate
- [ ] Descriptive and specific
- [ ] Creates scannable structure

**Flag:**
> ❌ "Account Creation Process Overview"
>
> ✅ "Creating your first account"

### Check Section Dividers
- [ ] Major sections separated with `---`
- [ ] Not overused (not every heading)
- [ ] Creates visual breathing room

### Check Navigation
- [ ] Links to related content
- [ ] Previous/Next links where appropriate
- [ ] On-this-page navigation for long content

---

## Completeness Review

### For Conceptual Documentation
- [ ] Definition/overview paragraph present
- [ ] Key characteristics listed
- [ ] "How it works" explained
- [ ] Related concepts linked
- [ ] Next steps provided

### For How-To Guides
- [ ] Prerequisites listed
- [ ] All steps included
- [ ] Verification step present
- [ ] Troubleshooting covered (if common issues exist)
- [ ] Next steps provided

### For API Documentation
- [ ] HTTP method and path documented
- [ ] All path parameters documented
- [ ] All query parameters documented
- [ ] All request body fields documented
- [ ] All response fields documented
- [ ] Required vs optional clear
- [ ] Request example provided
- [ ] Response example provided
- [ ] Error codes documented
- [ ] Deprecated fields marked

---

## Clarity Review

### Check Sentence Length
- [ ] One idea per sentence
- [ ] Sentences under 25 words (ideally)
- [ ] Complex ideas broken into multiple sentences

### Check Paragraph Length
- [ ] 2-3 sentences per paragraph
- [ ] One topic per paragraph
- [ ] White space between paragraphs

### Check Jargon
- [ ] Technical terms explained on first use
- [ ] Acronyms expanded on first use
- [ ] Common language preferred over jargon

### Check Examples
- [ ] Examples use realistic data
- [ ] Examples are complete (can be copied/used)
- [ ] Examples follow explanations immediately

---

## Technical Accuracy Review

### For Conceptual Content
- [ ] Facts are correct
- [ ] Behavior descriptions match actual behavior
- [ ] Version information is current
- [ ] Links work and go to correct destinations

### For API Documentation
- [ ] Endpoint paths are correct
- [ ] HTTP methods are correct
- [ ] Field names match actual API
- [ ] Data types are accurate
- [ ] Required/optional status is correct
- [ ] Examples are valid JSON/code
- [ ] Error codes match actual responses

### For Code Examples
- [ ] Code compiles/runs
- [ ] Output matches description
- [ ] No syntax errors
- [ ] Uses current API version

---

## Common Issues to Flag

### Voice Issues
| Issue | Example | Fix |
|-------|---------|-----|
| Third person | "Users can..." | "You can..." |
| Passive voice | "...is returned" | "...returns" |
| Future tense | "will provide" | "provides" |
| Conditional | "would receive" | "receives" |
| Arrogant tone | "Obviously..." | Remove |

### Structure Issues
| Issue | Example | Fix |
|-------|---------|-----|
| Title case | "Getting Started" | "Getting started" |
| Missing dividers | Wall of text | Add `---` |
| Deep nesting | H4, H5, H6 | Flatten or split |
| Vague headings | "Overview" | "Account overview" |

### Completeness Issues
| Issue | Example | Fix |
|-------|---------|-----|
| Missing prereqs | Steps without context | Add prerequisites |
| No examples | API without code | Add examples |
| Dead links | 404 errors | Fix or remove |
| Outdated info | Old version refs | Update |

### Clarity Issues
| Issue | Example | Fix |
|-------|---------|-----|
| Long sentences | 40+ words | Split |
| Wall of text | No bullets | Add structure |
| Undefined jargon | "DSL" unexplained | Define or link |
| Abstract examples | "foo", "bar" | Use realistic data |

---

## Review Output Format

When reviewing documentation, provide structured feedback.

> **Note:** Documentation reviews use `PASS/NEEDS_REVISION/MAJOR_ISSUES` verdicts, which differ from code review verdicts (`PASS/FAIL/NEEDS_DISCUSSION`). Documentation verdicts are graduated—most docs can be improved but may still be publishable with `NEEDS_REVISION`.

```markdown
## Review Summary

**Overall Assessment:** [PASS | NEEDS_REVISION | MAJOR_ISSUES]

### Voice and Tone
- [x] Second person usage ✓
- [ ] Active voice – Found 3 passive constructions
- [x] Appropriate tone ✓

### Issues Found

#### High Priority
1. **Line 45:** Passive voice "is created by" → "creates"
2. **Line 78:** Missing required field documentation

#### Medium Priority
1. **Line 23:** Title case in heading → sentence case
2. **Line 56:** Long sentence (42 words) → split

#### Low Priority
1. **Line 12:** Could add example for clarity

### Recommendations
1. Fix passive voice instances (3 found)
2. Add missing API field documentation
3. Convert headings to sentence case
```

---

## Quick Review Checklist

For rapid reviews, check these essentials:

**Voice (30 seconds)**
- [ ] "You" not "users"
- [ ] Present tense
- [ ] Active voice

**Structure (30 seconds)**
- [ ] Sentence case headings
- [ ] Section dividers present
- [ ] Scannable (bullets, tables)

**Completeness (1 minute)**
- [ ] Examples present
- [ ] Links work
- [ ] Next steps included

**Accuracy (varies)**
- [ ] Technical facts correct
- [ ] Code examples work
- [ ] Version info current