Author Workflow
What an author does from start to publication, across all five lanes.
Starting work
For every lane, the author creates a feature branch off main with the appropriate prefix. The branch prefix is what routes the PR to the right review lane — see Review Lanes for the mapping.
| Lane | Branch prefix | Initial setup |
|---|---|---|
| Lane 1: New document | docs/new/ | Scaffold the document directory and v1.0/ folder, register the document in src/docConfig.js with active: false, draft: true |
| Lane 2: Major revision | docs/major/ | Copy the previous version folder to a new vX.0/, mirror static/figures/, bibliographies/, and source-documents/, flip draft: true in src/docConfig.js, add a placeholder row to 00-version-history.mdx |
| Lane 3: Minor revision | docs/minor/ | Same as Lane 2 but for a minor version bump (e.g., v1.1/) |
| Lane 4: Editorial fix | docs/fix/ | Edit the file directly. No version change required. |
| Lane 5: Dev docs | docs/dev/ | Edit files under docs/dev/. No version change required. |
All steps can be performed in any IDE, via git on the command line, or entirely in the browser using github.dev (press . on any GitHub repo page to open a browser-based VS Code).
Opening the pull request
The author opens a PR via the GitHub web interface or an IDE's PR integration. The repository ships a PR template that prefills a description structure — the author fills in the Description, Affected documents, Related issues, Pre-submission checklist, and (for Lane 1) the Technical edit checkbox sections. If the author knows who the peer reviewer should be, they assign that person in the Reviewers sidebar; otherwise the site administrator assigns one.
Within a minute or two of opening the PR, three bot comments appear:
- A preview URL where reviewers will read the rendered document
- A stage progression comment identifying the lane and what review is needed next
- 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
Responding to review comments
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.
For suggested changes (pre-filled code blocks), the author can click Commit suggestion to apply the fix in one click.
All comment threads must be resolved before the PR can merge.
The technical edit (Lanes 1, 2, and 3)
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.
The author addresses each comment the same way as comments from human reviewers — pushing fixes, replying, and either the author or the site administrator resolves threads as they are addressed.
When all technical edit comments have been addressed, the author checks the checkbox in the PR description:
- [x] Technical edit comments addressed — ready for Director review
Checking this box advances the document to the next stage (Director review for Lane 1, ready-to-merge for Lanes 2 and 3). The author does not check the box until every comment has been addressed.
See Technical Edit for the full prompt the AI uses and the alternative human-editor path.
Where reviewers read the document
| Lane | Where review happens |
|---|---|
| Lane 1 | Peer review and Lead Civil review on the preview URL. Technical edit reads source MDX directly via inline PR comments (no deploy). Director review on the live production URL (watermarked). |
| Lane 2 | All review on the preview URL. |
| Lane 3 | All review on the preview URL. |
| Lane 4 | Site administrator reviews on the preview URL or directly in the Files changed tab, then merges. |
| Lane 5 | Site administrator reviews on the preview URL or directly in the Files changed tab, then merges. |
If the author pushes revisions during Director review, the site administrator re-deploys so the live URL stays current.
When reviewers ask for changes
Reviewers typically submit feedback as a Comment review (not Request changes), leaving inline notes on specific lines. The author addresses each comment, pushes a new commit, and replies to the thread explaining what was done. The stage progression bot automatically pings the assigned reviewer(s) to come back and backcheck.
The stage does not reset when the author pushes new commits. A revision during peer review is for the peer reviewer to backcheck; it does not send the document back to start. The same applies to Lead Civil review and Director review. This is intentional — each review round builds on the prior round, rather than restarting from scratch.
When the review is complete
The site administrator prepares the merge: flips the draft flag in src/docConfig.js, updates the version history, merges the PR, and approves the final deploy. The author receives email notifications as each step happens. Once the deploy completes, the document is live.