THE GITHTML FIELD GUIDE
Run a read-only release documentation review
A release documentation review should verify that readers can identify the release, complete the supported tasks, and understand changed behavior. Use read-only Git inspection plus rendered-page checks. Keep findings separate from fixes, and record the exact reviewed revision so approval does not accidentally apply to later unreviewed changes.
Set a review boundary
List the release identifier, candidate commit, target audience, and three essential user journeys. Examples include first installation, upgrade from the previous supported release, and recovery from a known configuration error. This makes the review finite and relevant.
Specify what is outside scope, such as a full API accuracy audit or translation review. A small honest review is more useful than a broad approval whose meaning nobody can explain after publication.
Inspect the changed documentation
Use git diff --name-status with the prior and candidate release references to identify changed documentation paths. Review modified commands and prerequisites first, then additions and removals that may affect navigation.
Look for version mismatches across headings, examples, screenshots, filenames, and compatibility statements. A release number in the page title does not ensure that every copied example was updated. Record uncertain claims as questions instead of silently assuming they are correct.
- Record the candidate commit and three reader journeys.
- Inspect changed documentation and walk each rendered journey.
- Report blockers with exact paths, then state the reviewed revision.
Walk the reader journeys
Open the rendered entry page and follow the links needed for each journey. Check whether warnings appear before risky steps, whether expected outputs are described, and whether the final success condition is observable.
For gitHtml reading copies, test the actual .html documents with the intended script and remote-resource settings. A local site preview may have access to assets that the reading copy lacks. These are different environments and require separate observations.
Issue a precise review result
Use a checklist containing release identity, prerequisite accuracy, task completeness, link checks, offline limitations, and unresolved blockers. For each failure, provide a path, section, observed issue, and expected correction. Avoid vague findings such as docs need polish.
State whether the review is approved, conditionally approved, or blocked, and name the reviewed commit. If the candidate changes afterward, revisit the affected pages rather than treating the earlier review as a blanket endorsement of whatever eventually ships.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.