Documentation Review Workflow

Verify that a change updates the docs, comments, and examples it makes stale, preventing documentation drift.

beginner~40 minreviewdocumentationquality

Objective

Keep documentation accurate as code changes.

Environment

Documentation sources
A diff of the change
Doc link checking

Steps

1. Identify affected docs

Find the docs, READMEs, and examples the change makes incorrect.

Expected state: Stale docs are identified.

2. Update or flag them

Update the docs in the same change or flag follow-up work explicitly.

Expected state: Docs match the new behaviour.

3. Check comments and examples

Update inline comments and code examples that no longer reflect the code.

Expected state: Comments and examples are accurate.

4. Verify links still resolve

Check that referenced links and anchors still exist.

Expected state: No documentation links are broken.

Decision points

Update docs in the same change?

Update in the same change when small
Flag follow-up for large docs

Update small docs inline; flag and track large documentation work.

Block merge on doc drift?

Block on user-facing docs
Never block

Block on user-facing API and behaviour docs; keep internal notes advisory.

Expected outcome

Documentation stays consistent with code because changes update it or flag follow-up work.

Verification

Confirm affected docs were updated and no links in them are broken.

Cleanup

Fix any documentation debt flagged during the review.

Overview

Keep documentation accurate as code changes.

This workflow is reusable across teams and environments; adapt the commands to your tooling while keeping the sequence and checkpoints intact.

Environment and prerequisites

Documentation sources
A diff of the change
Doc link checking

Procedure

1. Identify affected docs

Find the docs, READMEs, and examples the change makes incorrect.

Expected state: Stale docs are identified.

2. Update or flag them

Update the docs in the same change or flag follow-up work explicitly.

Expected state: Docs match the new behaviour.

3. Check comments and examples

Update inline comments and code examples that no longer reflect the code.

Expected state: Comments and examples are accurate.

4. Verify links still resolve

Check that referenced links and anchors still exist.

Expected state: No documentation links are broken.

# check documentation links
npx markdown-link-check README.md

Verification

Confirm affected docs were updated and no links in them are broken.

Decision points

Update docs in the same change?

Update in the same change when small
Flag follow-up for large docs

Recommendation: Update small docs inline; flag and track large documentation work.

Block merge on doc drift?

Block on user-facing docs
Never block

Recommendation: Block on user-facing API and behaviour docs; keep internal notes advisory.

Common failures

Stale docs mislead users.
Unchecked links rot over time.
Flagged follow-ups get lost.