# Reviewing Documentation

> Defines documentation-gap review and REQUIRED/RECOMMENDED findings. Load when assessing whether a diff needs user-facing docs.

- Skill: `bostonaholic/reviewing-documentation` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add bostonaholic/reviewing-documentation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bostonaholic/reviewing-documentation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: bostonaholic (https://skillmd.com/u/bostonaholic)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bostonaholic/reviewing-documentation

---


# Reviewing Documentation

Apply `skills/writing-prose/SKILL.md`, compare the diff with existing docs, and
classify each gap.

## Applying Prose Principles to Reviews

When the technical-writer agent identifies documentation gaps or assesses
documentation quality, apply the writing-prose principles:

1. **Classify by impact.** Weight readability and accuracy by affected readers.

2. **Name the failure mode.** Cite the violated rule and its reader effect.

3. **Suggest direction, not a rewrite.** The producer owns edits.

4. **Record what works.** A problem-only report is incomplete.

## Documentation-Gap Review Process

The technical-writer's procedure for reviewing a diff against existing
documentation:

1. **Read the diff.** Run `git diff HEAD~1` (or the applicable range) to
   understand what changed.

2. **Inventory existing documentation.** Search for:
   - Project README files (`**/README*`)
   - Documentation directories (`docs/`, `doc/`)
   - Inline documentation (JSDoc, docstrings, type definitions)
   - API documentation (OpenAPI specs, route comments)
   - Configuration documentation (environment variable docs, setup guides)
   - Changelog or release notes

3. **Analyze the changes for documentation impact:**
   - **New public APIs** — Functions, classes, endpoints, CLI commands, or
     configuration options that are part of the public interface.
   - **Changed behavior** — Existing functionality that now works differently.
   - **Removed functionality** — Features, APIs, or options that no longer exist.
   - **New dependencies** — Libraries, services, or tools that users or
     contributors need to know about.
   - **Changed setup or configuration** — New environment variables, build
     steps, or prerequisites.

4. **Cross-reference.** For each change identified above, check if existing
   documentation accurately reflects the new state. Look for:
   - Documentation that references removed code or old behavior
   - Code examples that no longer work
   - Setup instructions that are now incomplete
   - Type definitions or interfaces that changed but whose docs did not

## Doc-Change Classification

### REQUIRED

The documentation gap would cause users or contributors to fail. Examples:
- New public API with no documentation at all
- Setup instructions that are now incorrect
- Removed feature still documented as available
- New necessary environment variable not documented

### RECOMMENDED

The documentation gap could cause confusion but would not block usage. Examples:
- Complex feature that works but lacks usage examples
- Inline comments that are now stale
- Missing changelog entry for a notable change
- Type definitions that could benefit from JSDoc