A review workflow should make evidence visible and decisions reversible. It should also match the risk of the change: correcting a typo does not need the same process as documenting authentication, billing, migration, or destructive commands.
Define the roles
- Author: owns the reader problem, draft, and incorporated feedback.
- Technical reviewer: verifies behavior, prerequisites, examples, and edge cases.
- Editorial reviewer: checks structure, clarity, terminology, accessibility, and consistency.
- Approver: accepts the publication risk and confirms release readiness.
One person may hold several roles on a small team, but the decisions should remain explicit.
Collect evidence before review
Attach the product change, issue, design, tested environment, screenshots, example output, and known limitations. For code samples, record the version and command used to test them. Review is faster when reviewers can reproduce claims.
Use two review passes
- Technical pass: test the sequence and challenge assumptions about permissions, defaults, versions, and failure states.
- Reader pass: inspect information order, navigation, language, accessibility, and whether the page answers the intended question.
Do not bury technical approval inside general prose feedback. Record it explicitly.
Set risk-based approval rules
- Low risk: author review and automated checks.
- Medium risk: subject-matter review plus editorial review.
- High risk: reproducible technical validation, named approval, and a rollback plan.
Publish with maintenance metadata
At publication, record the owner, validation date, affected product version, and next review trigger. Link the documentation change to the release record so future maintainers can understand why it changed.
Close the feedback loop
Review does not end at publication. Watch search failures, support escalations, page feedback, and product completion signals. Route actionable findings back to the same ownership system.
Minimum review checklist
- The intended reader and task are stated.
- Prerequisites and permissions are complete.
- Instructions and examples were tested.
- Error recovery is documented where risk warrants it.
- Terminology and links are consistent.
- The owner and next review trigger are recorded.