Review and Approval Process Overview
This chapter and the six that follow describe the review and approval process for all documentation published on the RMC Software Documentation website. Read this chapter first for the high-level picture, then refer to the role-specific chapter that applies to the task at hand.
Participants
Six roles participate in the workflow. Only the author needs local development tooling; every other role works in a web browser.
| Role | Responsibility |
|---|---|
| Author | Writes or revises the document. The only role that needs local development tooling. |
| Peer reviewer | Subject-matter expert assigned ad-hoc to review technical accuracy on the preview URL. Works entirely in the GitHub web interface. |
| RMC Lead Civil | Provides technical oversight and quality assurance. Assigned ad-hoc per document. Reviews on the preview URL. |
| Technical edit (AI-assisted) | AI-powered editorial review covering grammar, clarity, tense, terminology, and Section 508 accessibility. A team member with the necessary tooling triggers the review; the AI posts inline comments on the PR. A human technical editor can be substituted at the site admin's discretion. |
| Director | The RMC Director provides final approval for new documents only, in a separate full-document Director Review PR after draft publication. |
| Site administrator | Classifies PRs, assigns one named reviewer per stage, records exceptions, merges to main, and approves production. |
The five review lanes
Every documentation change falls into one of five lanes based on its scope.
| Lane | Use case | Review chain |
|---|---|---|
| Lane 1: New document | A new document being added to the site | Content PR: Peer → Lead Civil → Technical edit; then separate Director Review and Publication PRs |
| Lane 2: Major revision | Substantial changes warranting a new major version (e.g., v1.0 → v2.0) | Peer → Lead Civil → Technical edit |
| Lane 3: Minor revision | Smaller updates warranting a minor version bump (e.g., v1.0 → v1.1) | Peer → Technical edit |
| Lane 4: Editorial fix | Typos, broken links, grammatical corrections — no technical change | None (site admin self-merges) |
| Lane 5: Dev docs | Any change to documents under docs/dev/ (developer guides, internal references) | None (site admin self-merges) |
For a new document, peer, Lead Civil, and technical editing happen in the Content PR. That PR then merges to main and deploys as a draft. An administrator starts a separate Director Review PR with a stable full-document preview; approval or waiver produces a Publication PR.
Only a new document requires Director review. Major and minor revisions finish after technical editing; editorial, developer-documentation, and code changes have no formal document stages.
See Review Lanes for branch-prefix conventions and detailed examples.
Changes outside the lanes
The five lanes cover documentation. They do not cover the rest of the repository — React components, CSS, build scripts, Docusaurus configuration, and GitHub workflows.
Every PR receives an administrator classification. A code-only PR uses /review classify code - and has no formal document stages; current required CI and administrator merge still apply.
Branch prefixes are descriptive conventions. The administrator's recorded classification is authoritative.
A pull request that changes site code and documentation is a documentation PR and needs a docs/ branch prefix. See Changes with no review lane for the full treatment.
The merge gate
Every PR carries a GitHub commit status called review-workflow that functions as the merge gate. Branch protection on main requires this status to be success before a PR can merge, so no participant — not even a site administrator — can merge a PR whose review is incomplete. For documentation PRs the stage progression workflow sets it; for PRs with no review lane, the CI build sets it to success as soon as the build passes.
| Situation | Status |
|---|---|
| Any active review stage (peer, Lead Civil, AI editor, Director, or needs-lane) | pending |
| Controller reports all required stages complete or waived | success |
| lane:editorial-fix or lane:dev assigned | success (immediately) |
| Non-docs PR, CI Build passed | success |
The status is re-evaluated on every push to a PR. The goal is that the merge button reflects the workflow's judgment, not the administrator's discretion.
The draft watermark
Documents flagged as drafts display a large diagonal "DRAFT" watermark. A new-document Content PR deploys from main with this watermark before separate Director review. The Publication PR removes draft status after Director approval or waiver.
For Lanes 2 and 3, the document under revision exists only on the preview site during review. The currently-published version on the live site is never watermarked.
The watermark is version-aware: it renders only on the latest version of a flagged document. Older versions of the same document — accessible via direct URL — stay unwatermarked.
Where to go next
- Authoring a document: see Review Lanes and Author Workflow
- Reviewing as a peer or Lead Civil: see Reviewer Workflow
- Running a technical edit: see Technical Edit
- Director approval for a new document: see Director Workflow
- Site administration: see Site Admin Workflow