Author Workflow
What an author does from start to publication, across all five lanes.
Starting work
For every classification, the author creates a feature branch off main with the descriptive prefix. An administrator records the authoritative classification; the branch name does not control review state.
| 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 one PR for the document via GitHub or an IDE integration and fills in the repository template. Identify the document and its doc_location, related issues, and validation. The administrator classifies the PR and assigns one named reviewer per required stage.
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
- One persistent controller summary showing classification, the current named reviewer, completed or waived stages, preview, and next action
For the reviewer's view of these same three bot comments — and the rest of the page a reviewer lands on — see Reviewer Workflow.
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.
Answer related threads from Files changed using Start a review, then submit the batch together. This reduces separate review submissions and notification noise, although exact GitHub email behavior depends on each user's settings. See Reviewer Workflow §5.
For suggested changes (pre-filled code blocks), the author can click Commit suggestion to apply the fix in one click.
Replies and resolved threads help collaboration but are not automated stage or merge gates.
Authors writing clear, descriptive commit messages make a reviewer's life much easier — see Reviewer Workflow §3 — Navigating commits within a PR for how a reviewer uses your commit messages to focus their attention.
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.
Technical editing is manually initiated. When it has actually finished, an administrator records /review complete editor. An author checkbox does not advance the workflow. Major and minor revisions need no Director review. A new-document Content PR merges and deploys as a draft before its separate Director Review PR begins.
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. |
Director corrections are pushed to the separate Director Review PR, whose stable preview updates without publishing its branch to production.
When reviewers ask for changes
Reviewers use Comment, Request changes, or Approve as appropriate. The author addresses feedback and may use /review ready to request renewed attention.
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
Only an administrator merges to main and approves production. Major and minor revisions follow their normal merge. A new document's Content PR retains draft: true; Director approval or waiver later creates a separate Publication PR that removes draft status. Document attribution is updated manually.