Skip to content

Commit 46cdce4

Browse files
committed
Rework Reviewer Workflow as a screenshot-driven walkthrough
New chapter structure: linear, beginner-oriented, built around 16 annotated figures and GIFs captured against the permanent training sandbox PR #121. Covers the full reviewer lifecycle from email notification through submitting the review and backchecking the author's revisions. Adds cross-links into the new chapter from the Author and Site Admin Workflow chapters. Removes the planning artifacts and capture/annotation scripts that produced the figures (history preserves them for future re-captures).
1 parent 5e19859 commit 46cdce4

76 files changed

Lines changed: 452 additions & 4478 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

docs/dev/documentation-guide/11-author-workflow.mdx

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,8 @@ Within a minute or two of opening the PR, three bot comments appear:
5656
2. A stage progression comment identifying the lane and what review is needed next
5757
3. A hidden state comment that renders as an "Assigned reviewers for this PR" block, tracking which individuals the site administrator has assigned to each review stage
5858

59+
For the reviewer's view of these same three bot comments — and the rest of the page a reviewer lands on — see [Reviewer Workflow](./12-reviewer-workflow.mdx).
60+
5961
## Responding to review comments
6062

6163
Reviewers post comments on specific lines in the Files changed tab. For each comment, the author makes the fix, pushes a commit, and replies explaining what was done. The reviewer resolves the thread when satisfied.
@@ -64,6 +66,8 @@ For suggested changes (pre-filled code blocks), the author can click **Commit su
6466

6567
**All comment threads must be resolved before the PR can merge.**
6668

69+
Authors writing clear, descriptive commit messages make a reviewer's life much easier — see [Reviewer Workflow §3 — Navigating commits within a PR](./12-reviewer-workflow.mdx#navigating-commits-within-a-pr) for how a reviewer uses your commit messages to focus their attention.
70+
6771
## The technical edit (Lanes 1, 2, and 3)
6872

6973
After the previous review stage approves the PR, the technical edit stage begins. A team member triggers an AI-assisted technical edit against the PR. The AI reads the source MDX files directly and posts inline review comments covering grammar, tense, clarity, terminology, and Section 508 accessibility. The document is not yet deployed to the live site at this stage — the technical edit works on source files, so the live deploy is deferred until the technical edit is complete.

docs/dev/documentation-guide/12-reviewer-workflow.mdx

Lines changed: 446 additions & 37 deletions
Large diffs are not rendered by default.

docs/dev/documentation-guide/15-site-admin-workflow.mdx

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,8 @@ Reviewers are assigned ad-hoc per PR via the Reviewers sidebar (gear icon → ty
3737

3838
For Lane 1, the site administrator assigns up to three people across the lifecycle: the peer reviewer (if the author did not), the Lead Civil after peer approval, and the Director after the technical edit.
3939

40+
For what the assigned reviewer experiences from the email notification through submitting their review, see [Reviewer Workflow](./12-reviewer-workflow.mdx). This is especially useful context when onboarding a first-time reviewer.
41+
4042
**Per-individual gating.** When the site administrator assigns someone via the Reviewers sidebar, the stage progression workflow records that person in a hidden state comment on the PR, keyed by the current review stage. Only approvals from those assigned reviewers advance the stage — drive-by approvals from other team members are logged but ignored by the workflow. Multiple people can be assigned at the same stage; the first approval from any of them advances the PR.
4143

4244
To replace an assigned reviewer, the site administrator removes them from the Reviewers sidebar and adds the correct person. The state comment updates automatically.

0 commit comments

Comments
 (0)