Documentation Review Checklist: [Page, pull request or release name]
Review gate for one documentation page, one docs pull request or one
docs release: scope and trigger, reviewer roles, workflow, severity
rules, and nine checklists covering technical accuracy with subject
matter expert (SME) sign-off, task testability, style, terminology,
links, runnable code samples, accessibility against WCAG 2.2 (W3C
Recommendation, 12 December 2024), localisation readiness and
Diátaxis type purity, followed by a findings log and the sign-off.
Structure aligned with the test and review concepts of ISO/IEC/IEEE
26513:2017 (requirements for testers and reviewers of information for
users) and with the Diátaxis documentation framework. Replace every
[bracketed] value and every row marked Example.
Document control
| Field | Value |
|---|
| Document ID | [DRC-001] |
| Item under review | [Page path, pull request number or docs release tag] |
| Content version or commit | [Commit SHA or docs version] |
| Product version documented | [Product name] [Version] |
| Diátaxis type(s) | [Tutorial / How-to guide / Reference / Explanation] |
| Review type | [New page / Major revision / Minor edit / Release review] |
| Version | [0.1] |
| Status | [Draft / In review / Approved / Approved with conditions / Rejected] |
| Owner | [@docs-owner] |
| Approvers/reviewers | [@sme], [@editor], [@accessibility-reviewer], [@localisation-lead] |
| Review window | YYYY-MM-DD to YYYY-MM-DD |
| Classification | [Public / Internal] |
| Last updated | YYYY-MM-DD |
Approvals
| Role | Name | Decision | Date |
|---|
| Subject matter expert | [@name] | [Approve / Approve with conditions / Reject] | YYYY-MM-DD |
| Docs editor | [@name] | [Decision] | YYYY-MM-DD |
| Docs owner (final sign-off) | [@name] | [Decision] | YYYY-MM-DD |
Revision history
| Version | Date | Author | Change summary |
|---|
| 0.1 | YYYY-MM-DD | [@name] | First review pass recorded |
| 0.2 | YYYY-MM-DD | [@name] | Example: SME findings added after test run |
| 1.0 | YYYY-MM-DD | [@name] | Example: All blocking findings closed, approved for publish |
Contents
1. Review scope and trigger
| Item | Value |
|---|
| Trigger | [New feature / Product change / Defect report / Scheduled re-verification / Audit finding] |
| Pages in scope | [List of page paths] |
| Pages explicitly out of scope | [List, with reason] |
| Related product change | [Ticket, pull request or release note entry] |
| Environment used for testing | [Product version, plan or tier, operating system, browser] |
| Checklists that apply | [A, B, C, D, E, F, G, H, I] |
| Checklists marked N/A | [For example: F, the page has no code; reason recorded] |
Example: Corvid Commerce adds an order.refunded webhook event. The
pull request changes the how-to guide "Receive order events with
webhooks" and the reference page "Webhook event types". Both pages are
in scope; the "Webhooks explained" page is out of scope because no
concept changed. All nine checklists apply.
Use these depth rules to keep effort proportional:
| Review type | Minimum checklists | Who must sign |
|---|
| New page | All nine | SME, editor, docs owner |
| Major revision (procedure, default, limit or behaviour changes) | A, B, C, D, E, F, G, I; H when the page is localised | SME, editor, docs owner |
| Minor edit (typo, wording, link fix) | C, D, E | Editor |
| Release review | All nine on a sample of pages chosen by risk | Docs owner, plus SME per area |
2. Reviewer roles and responsibilities
| Role | Responsibility | Checklists owned | Name |
|---|
| Author | Prepares the page, runs the automated checks, answers findings | Pre-review self-check of all lists | [@author] |
| Subject matter expert (SME) | Confirms the content is technically true for the stated version | A, F | [@sme] |
| Task tester | Follows every step on a clean environment exactly as written | B | [@tester] |
| Docs editor | Style, voice, structure, terminology, links, type purity | C, D, E, I | [@editor] |
| Accessibility reviewer | Checks images, headings, links, media and diagrams | G | [@a11y-reviewer] |
| Localisation lead | Confirms the source is ready for translation | H | [@l10n-lead] |
| Docs owner | Resolves disputes, takes the publish decision | Section 15 | [@docs-owner] |
- Review the rendered preview as well as the source. Many defects
(broken tables, collapsed lists, missing images) only show when
rendered.
- Record every finding in section 14, even when you fix it yourself,
so the pattern is visible in the next content audit.
- Comment on the content, not on the author. Suggest a fix with each
finding where you can.
- An SME confirms facts; the SME does not rewrite for style. An editor
improves wording; the editor does not change facts without the SME.
3. Review workflow
| Step | Entry condition | Exit condition | Target duration |
|---|
| 1. Author self-check | Draft complete | All lists pre-checked by the author | [1 day] |
| 2. Automated checks | Pull request opened | Style linter, Markdown linter, link checker and docs build pass | [Minutes] |
| 3. SME review and task test | Automated checks pass | Checklists A, B and F complete | [2 business days] |
| 4. Editorial review | SME review complete | Checklists C, D, E and I complete | [1 business day] |
| 5. Accessibility and localisation | Editorial review complete | Checklists G and H complete | [1 business day] |
| 6. Sign-off | No open Blocker or Major findings | Decision recorded in section 15 | [Same day] |
The automated tooling (style linter rules, Markdown linter configuration,
link checker) is defined in the Docs Contribution Guide
(docs/docs-contribution-guide). Do not duplicate its configuration
here; record only whether each tool passed in section 15.
4. Severity and decision rules
| Severity | Meaning | Publish rule |
|---|
| Blocker | The reader would fail, lose data, create a security exposure or break the law by following the page | Must be fixed before publish |
| Major | A step, value or claim is wrong or missing and the reader would likely get stuck; an accessibility barrier exists | Must be fixed before publish, or the docs owner accepts it in writing with a fix date |
| Minor | The reader can succeed but with friction: unclear wording, a missing cross-link, inconsistent term | Fix before publish or log for the next edit |
| Suggestion | Improvement idea with no defect | Optional |
- Any open Blocker means Reject.
- Any open Major without a written acceptance means Reject.
- Open Majors with acceptance, or more than [5] open Minors, means
Approve with conditions, with the conditions listed in section 15.
- Otherwise, Approve.
5. Checklist A: Technical accuracy
| ID | Check | How to verify | Result | Finding |
|---|
| TA-01 | Every factual claim (behaviour, default, limit, quota, price, timing) matches the documented product version | Compare with the source code, API description, configuration schema or product UI | [Pass / Fail / N/A] | [DRF-NNN] |
| TA-02 | Names of UI elements, commands, parameters, fields and error messages match the product exactly | Compare character by character with the product or generated reference | [Result] | [Finding] |
| TA-03 | Version applicability is stated (which versions, plans, editions or platforms the page covers) | Read the page header or applicability note | [Result] | [Finding] |
| TA-04 | Prerequisites and permissions needed are complete and correct | Try the task with a role that has only the listed permissions | [Result] | [Finding] |
| TA-05 | Warnings cover every step that can destroy data, expose secrets or cause cost | SME lists risky steps and confirms each carries a warning | [Result] | [Finding] |
| TA-06 | Security guidance is current: no hard-coded secrets, least privilege shown, insecure options labelled | SME and security champion review | [Result] | [Finding] |
| TA-07 | Limits, rate limits and error behaviour match the service contract | Compare with the reference page and the service level documents | [Result] | [Finding] |
| TA-08 | Deprecated features are marked and point to the replacement | Compare with the deprecation notice and changelog | [Result] | [Finding] |
| TA-09 | Screenshots and diagrams reflect the current UI and architecture | Compare with the running product | [Result] | [Finding] |
| TA-10 | The SME has recorded a sign-off with name and date in the approvals table | Check the approvals table | [Result] | [Finding] |
Example: TA-01 Fail, finding DRF-001: the page states that webhook
retries stop after 3 attempts; the Corvid Commerce delivery service
retries 8 times over 24 hours.
6. Checklist B: Task testability
| ID | Check | How to verify | Result | Finding |
|---|
| TB-01 | The tester followed every step literally, in order, on a clean environment | Tester notes environment and start state | [Pass / Fail / N/A] | [DRF-NNN] |
| TB-02 | Each step has one action, and the expected result is stated after any step that changes state | Read each step | [Result] | [Finding] |
| TB-03 | The end state is stated and verifiable ("You should now see ...") | Tester confirms the stated result appeared | [Result] | [Finding] |
| TB-04 | No step relies on knowledge the page does not give or link to | Tester flags every point where they had to guess | [Result] | [Finding] |
| TB-05 | Optional and conditional steps are clearly marked with their condition | Read conditional steps | [Result] | [Finding] |
| TB-06 | Error paths that a reader is likely to hit are covered or linked to troubleshooting | Tester deliberately triggers the most common error | [Result] | [Finding] |
| TB-07 | Cleanup or rollback is described when the task creates resources that cost money or hold data | Tester performs the cleanup | [Result] | [Finding] |
| TB-08 | Time to complete is realistic if the page states one | Tester records actual time | [Result] | [Finding] |
| Test run | Tester | Environment | Start state | Result | Time taken |
|---|
| RUN-001 (Example) | [@tester] | Corvid Commerce sandbox, v[5.2], Linux, Chrome | New sandbox account, no webhooks | Completed with one guess at step 4 (DRF-002) | 14 minutes |
| [RUN-NNN] | [@name] | [Environment] | [State] | [Result] | [Minutes] |
7. Checklist C: Style and voice
| ID | Check | How to verify | Result | Finding |
|---|
| ST-01 | The page follows the organisation style guide (docs/style-guide-technical) | Style linter passes; editor reads the page | [Pass / Fail / N/A] | [DRF-NNN] |
| ST-02 | Second person, active voice and present tense in instructions | Editor reads instructions | [Result] | [Finding] |
| ST-03 | Headings are task or topic based, parallel in form and in sentence case if the guide requires it | Read the heading outline | [Result] | [Finding] |
| ST-04 | Sentences are short; one idea per paragraph; lists used for sequences and sets | Editor read-through | [Result] | [Finding] |
| ST-05 | No marketing language, idioms, jokes or culture-specific references that block understanding | Editor read-through | [Result] | [Finding] |
| ST-06 | Inclusive language: no gendered defaults, no ableist or exclusionary terms | Linter rule and editor read-through | [Result] | [Finding] |
| ST-07 | Numbers, dates, units and UI formatting follow the guide (bold for UI labels, code font for literals) | Editor read-through | [Result] | [Finding] |
| ST-08 | The page title and description tell the reader what they will get | Read title, description metadata and first paragraph (maps to 2.4.2 Page Titled (A)) | [Result] | [Finding] |
8. Checklist D: Terminology
| ID | Check | How to verify | Result | Finding |
|---|
| TM-01 | Every product term matches the preferred term in the Termbase (docs/termbase) | Linter vocabulary list plus editor check | [Pass / Fail / N/A] | [DRF-NNN] |
| TM-02 | No deprecated or rejected terms appear | Linter reject list | [Result] | [Finding] |
| TM-03 | Each new term is defined at first use or linked to the Glossary (docs/glossary) | Editor check | [Result] | [Finding] |
| TM-04 | Abbreviations are expanded at first use on the page | Editor check | [Result] | [Finding] |
| TM-05 | Trademarks and third-party product names are spelled as their owners spell them | Editor check | [Result] | [Finding] |
| TM-06 | New terms introduced by this change have a termbase entry request | Check the termbase change log | [Result] | [Finding] |
9. Checklist E: Links and references
| ID | Check | How to verify | Result | Finding |
|---|
| LK-01 | Link checker reports no broken internal or external links | Link checker output attached to the pull request | [Pass / Fail / N/A] | [DRF-NNN] |
| LK-02 | Each link goes to the most specific relevant page or anchor, not a home page | Editor follows each link | [Result] | [Finding] |
| LK-03 | External links go to authoritative, stable sources; versioned links where the source versions | Editor check | [Result] | [Finding] |
| LK-04 | Moved or renamed pages have redirects, per the information architecture | Check redirect map (docs/information-architecture) | [Result] | [Finding] |
| LK-05 | Cross-links to the other Diátaxis types are present where a reader would need them | Editor check | [Result] | [Finding] |
| LK-06 | Links to known issues, release notes and changelog entries are current | Compare with Known Issues (docs/known-issues) | [Result] | [Finding] |
10. Checklist F: Code samples
| ID | Check | How to verify | Result | Finding |
|---|
| CS-01 | Every copyable sample runs without modification against the stated version, or placeholders are obvious and explained | Run each sample; CI sample tests where they exist | [Pass / Fail / N/A] | [DRF-NNN] |
| CS-02 | Samples contain no real credentials, tokens, personal data or internal hostnames | Secret scanner plus SME check | [Result] | [Finding] |
| CS-03 | Fenced code blocks declare a language for highlighting | Markdown linter | [Result] | [Finding] |
| CS-04 | Command prompts and output are separated so copy-paste works | Copy each block into a terminal | [Result] | [Finding] |
| CS-05 | Expected output is shown for commands whose output the reader must check | Read samples | [Result] | [Finding] |
| CS-06 | Samples show secure defaults (TLS, signature verification, least privilege scopes) | SME check | [Result] | [Finding] |
| CS-07 | Dependencies and their versions are stated for each sample | SME check | [Result] | [Finding] |
| CS-08 | Long samples link to a complete, maintained repository or file | Follow the link | [Result] | [Finding] |
Example: CS-06 Fail, finding DRF-003: the Node.js webhook receiver
sample parses the body before verifying the signature header. The SME
supplies a corrected sample that verifies first.
11. Checklist G: Accessibility
| ID | Check | WCAG 2.2 success criterion | Result | Finding |
|---|
| AC-01 | Every informative image has alt text that conveys its purpose; decorative images have empty alt text | 1.1.1 Non-text Content (A) | [Pass / Fail / N/A] | [DRF-NNN] |
| AC-02 | Complex diagrams have a text equivalent (caption, description or the Mermaid source in a details block) | 1.1.1 Non-text Content (A) | [Result] | [Finding] |
| AC-03 | Headings form a logical outline with no skipped levels (a house rule, not a WCAG failure on its own); one H1 | 1.3.1 Info and Relationships (A); 2.4.6 Headings and Labels (AA) | [Result] | [Finding] |
| AC-04 | Tables have header rows and are used for data, not layout | 1.3.1 Info and Relationships (A) | [Result] | [Finding] |
| AC-05 | Link text says where the link goes; no bare "click here" or "this page" | 2.4.4 Link Purpose (In Context) (A) | [Result] | [Finding] |
| AC-06 | Instructions do not rely only on shape, colour, size or position ("the green button on the right") | 1.3.3 Sensory Characteristics (A); 1.4.1 Use of Color (A) | [Result] | [Finding] |
| AC-07 | Text in diagrams and essential callouts meets contrast; screenshots used to convey instructions are legible (house rule where the 1.4.3 incidental-text exception applies); lines and shapes that carry meaning meet non-text contrast | 1.4.3 Contrast (Minimum) (AA); 1.4.11 Non-text Contrast (AA) | [Result] | [Finding] |
| AC-08 | No important text exists only as an image of text | 1.4.5 Images of Text (AA) | [Result] | [Finding] |
| AC-09 | Videos have accurate captions and a descriptive transcript or audio description; audio-only or video-only media have an alternative (see Screencast Script (docs/screencast-script)) | 1.2.1 Audio-only and Video-only (Prerecorded) (A); 1.2.2 Captions (Prerecorded) (A); 1.2.3 Audio Description or Media Alternative (Prerecorded) (A); 1.2.5 Audio Description (Prerecorded) (AA) | [Result] | [Finding] |
| AC-10 | Passages in another language are marked with their language | 3.1.2 Language of Parts (AA) | [Result] | [Finding] |
| AC-11 | Wide tables and code blocks scroll within their container and the page reflows at narrow widths | 1.4.10 Reflow (AA) | [Result] | [Finding] |
Record the tools used (for example an automated accessibility engine
plus a screen reader spot check) in the findings log. Automated tools
find only part of the issues; AC-01, AC-02, AC-05 and AC-06 need human
judgement.
12. Checklist H: Localisation readiness
| ID | Check | How to verify | Result | Finding |
|---|
| LR-01 | Sentences are complete and unambiguous; no strings built from fragments | Editor and localisation lead read-through | [Pass / Fail / N/A] | [DRF-NNN] |
| LR-02 | Terms match the termbase so translation memory and termbase lookups hit | Termbase check | [Result] | [Finding] |
| LR-03 | Text that must not be translated (code, commands, product names) is in code font or marked as do-not-translate | Localisation lead check | [Result] | [Finding] |
| LR-04 | Screenshots avoid embedded text where possible, or have a plan for localised captures | Localisation lead check | [Result] | [Finding] |
| LR-05 | Dates, numbers, currencies and units use an unambiguous format (ISO 8601 dates, explicit currency codes) | Editor check | [Result] | [Finding] |
| LR-06 | Layout tolerates text expansion and right-to-left scripts where in scope | Preview with a pseudo-localised build | [Result] | [Finding] |
| LR-07 | No idioms, puns or wordplay that cannot be translated | Editor check | [Result] | [Finding] |
| LR-08 | Translator notes are added for ambiguous strings | Check the notes file or comments | [Result] | [Finding] |
13. Checklist I: Diátaxis type purity
| ID | Check | How to verify | Result | Finding |
|---|
| DT-01 | The page has one declared type, recorded in its metadata | Read front matter | [Pass / Fail / N/A] | [DRF-NNN] |
| DT-02 | Tutorial: a guided lesson with a safe, repeatable path and a visible result at each stage; no choices, no deep explanation | Editor check | [Result] | [Finding] |
| DT-03 | How-to guide: addresses one real goal for a reader who already knows the basics; steps only, explanation linked out | Editor check | [Result] | [Finding] |
| DT-04 | Reference: neutral, complete and structured like the thing it describes; no instructions or opinions | Editor check | [Result] | [Finding] |
| DT-05 | Explanation: discusses context, reasons and alternatives; no step-by-step instructions | Editor check | [Result] | [Finding] |
| DT-06 | Content belonging to another type has been moved and linked rather than kept inline | Editor check | [Result] | [Finding] |
| DT-07 | The page sits in the navigation section for its type, per the information architecture | Check the site map | [Result] | [Finding] |
Example: DT-03 Fail, finding DRF-004 (Minor): the webhook how-to
spends three paragraphs on why HMAC signatures are used. Move them to
"Webhooks explained" and leave a one-line link.
14. Findings log
| Finding ID | Check | Severity | Location | Description | Proposed fix | Owner | Status |
|---|
| DRF-001 (Example) | TA-01 | Blocker | how-to/receive-order-events, step 6 | Retry count stated as 3; service retries 8 times over 24 hours | Replace with values from the delivery service reference | [@author] | Fixed, verified by [@sme] |
| DRF-002 (Example) | TB-04 | Major | how-to/receive-order-events, step 4 | Page does not say where to find the signing secret | Add the console path and link to the reference | [@author] | Fixed |
| DRF-003 (Example) | CS-06 | Major | Code sample "receiver.js" | Body parsed before signature verification | Use the SME-supplied sample | [@sme] | Fixed |
| DRF-004 (Example) | DT-03 | Minor | how-to/receive-order-events, intro | Explanation mixed into a how-to guide | Move to explanation page, add link | [@author] | Open, next edit |
| DRF-005 (Example) | AC-01 | Major | Screenshot "webhook-settings.png" | Alt text is the file name | Write alt text describing the settings panel state | [@author] | Fixed |
| [DRF-NNN] | [Check ID] | [Severity] | [Page and location] | [What is wrong] | [Fix] | [@owner] | [Open / Fixed / Accepted / Won't fix] |
Summary of the example log: 5 findings, of which 1 Blocker, 3 Major and
1 Minor; 4 fixed and 1 open Minor. Recount these figures whenever you
change the log.
15. Sign-off and publish decision
| Item | Value |
|---|
| Style linter | [Pass / Fail], tool and version [name x.y.z] |
| Markdown linter | [Pass / Fail], tool and version [name x.y.z] |
| Link checker | [Pass / Fail] |
| Docs build and preview | [Pass / Fail], preview URL [link] |
| Open Blocker findings | [0] |
| Open Major findings (accepted in writing) | [0] |
| Open Minor findings | [Number] |
| Decision | [Approve / Approve with conditions / Reject] |
| Conditions (if any) | [Condition, owner, due date] |
| Last verified date to record on the page | YYYY-MM-DD |
| Next verify date | YYYY-MM-DD ([6 / 12] months, or at next product release) |
| Signed by | [@docs-owner], YYYY-MM-DD |
Example: Decision Approve: the one open finding is Minor (DRF-004)
and is scheduled for the next edit. Next verify date set 6 months out
because webhook behaviour changes often.
16. Traceability of checks to sources
| Checklist | Check IDs | Source or rule | Note |
|---|
| A Technical accuracy | TA-01 to TA-10 | ISO/IEC/IEEE 26513:2017 review concepts (technical review by qualified reviewers) | Concept alignment only; no ISO text reproduced |
| B Task testability | TB-01 to TB-08 | ISO/IEC/IEEE 26513:2017 test concepts (testing information against the real system and with representative users) | Concept alignment only |
| C Style and voice | ST-01 to ST-08 | Technical Style Guide (docs/style-guide-technical) | Internal rule |
| D Terminology | TM-01 to TM-06 | Termbase (docs/termbase), Glossary (docs/glossary) | Internal rule |
| E Links | LK-01 to LK-06 | Information Architecture (docs/information-architecture) | Internal rule |
| F Code samples | CS-01 to CS-08 | Docs Contribution Guide (docs/docs-contribution-guide) | Internal rule |
| G Accessibility | AC-01 to AC-11 | WCAG 2.2, success criteria listed per row | Level A and AA |
| H Localisation readiness | LR-01 to LR-08 | Localisation Brief (docs/localization-brief) | Internal rule |
| I Diátaxis type purity | DT-01 to DT-07 | Diátaxis framework (diataxis.fr) | CC BY-SA 4.0 concepts, adapted |
17. Glossary and references
17.1 Glossary
| Term | Meaning in this checklist |
|---|
| SME | Subject matter expert who confirms technical truth for the stated version |
| Task test | Following a procedure literally on a clean environment to confirm it works |
| Finding | A recorded failure of one check, with severity and owner |
| Type purity | A page serving one Diátaxis form only |
| Verify date | The date the content was last confirmed as accurate |
| Pseudo-localisation | A build that replaces source text with expanded, accented text to expose layout and string problems before translation |
17.2 References
| Reference | Version or date checked | Use |
|---|
| ISO/IEC/IEEE 26513:2017, Systems and software engineering: Requirements for testers and reviewers of information for users | Edition 1, 2017; a second edition titled "Testing and reviewing of information for users" was at final draft stage when checked on 2026-10-24 | Review and test concepts, structure only |
| W3C, Web Content Accessibility Guidelines (WCAG) 2.2, https://www.w3.org/TR/WCAG22/ | W3C Recommendation, 12 December 2024 | Success criteria numbers and short names |
| Diátaxis, Daniele Procida, https://diataxis.fr/ | Checked 2026-10-24 | The four documentation forms |
| Google developer documentation style guide, https://developers.google.com/style | Checked 2026-10-24 | Further reading for style rules (CC BY 4.0); no text adapted |
| [Internal style guide, termbase, contribution guide] | [Version] | [Rules applied] |
Standard and licence note
Structure aligned with the test and review concepts of ISO/IEC/IEEE
26513:2017 (requirements for testers and reviewers of information for
users); no ISO text, table or definition is reproduced, and only the
standard's name and general concepts are referenced. Accessibility
checks cite WCAG 2.2 (W3C Recommendation, 12 December 2024) by success
criterion number and short name only; the WCAG text is available under
the W3C Document License. Checklist I adapts the four documentation
forms of the Diátaxis framework by Daniele Procida (https://diataxis.fr),
licensed under CC BY-SA 4.0
(https://creativecommons.org/licenses/by-sa/4.0/); material adapted from
Diátaxis is shared under the same licence, so if you adapt Checklist I
further you must keep this attribution and share it under CC BY-SA 4.0.
This template is otherwise original text written for this collection.
ISO/IEC/IEEE 26513 is being revised: check the current official
editions of every cited standard before use. Template licence: MIT.