From 53cea82e8b289a73ff85abfab0df6661bc40de2e Mon Sep 17 00:00:00 2001 From: Adam Gohs Date: Tue, 19 May 2026 10:15:21 -0400 Subject: [PATCH 1/7] Update CLAUDE.md for review workflow and docConfig.js - Fix docs/00-documentation-guide/ -> docs/dev/documentation-guide/ - Add missing npm scripts (report-map, image-dims, generate-toc) and DOCS_MODE note - Document src/docConfig.js as central active/draft registry - Add branching strategy table mapping prefixes to review lanes - Drop the user-facing Claude Code Skills section - Replace the QC section with a manual prompt-template description --- CLAUDE.md | 89 ++++++++++++------- ...> 16-appendix-a-source-code-structure.mdx} | 0 ... 17-appendix-b-build-process-overview.mdx} | 0 ...=> 18-appendix-c-search-configuration.mdx} | 0 4 files changed, 59 insertions(+), 30 deletions(-) rename docs/dev/documentation-guide/{09-appendix-a-source-code-structure.mdx => 16-appendix-a-source-code-structure.mdx} (100%) rename docs/dev/documentation-guide/{10-appendix-b-build-process-overview.mdx => 17-appendix-b-build-process-overview.mdx} (100%) rename docs/dev/documentation-guide/{11-appendix-c-search-configuration.mdx => 18-appendix-c-search-configuration.mdx} (100%) diff --git a/CLAUDE.md b/CLAUDE.md index 1a14a62e5..dc7bf0e8d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -5,14 +5,18 @@ This is the official documentation site for the **RMC (Risk Management Center) s ## Quick Commands ```bash -npm start # Start dev server (runs all generation scripts first) -npm run build # Build static site for production -npm run counters # Generate figure/table/equation counters -npm run sidebars # Generate sidebar navigation from MDX files -npm run versions # Extract version metadata -npm run report-map # Create reportIdMap.js for document routing +npm start # Start dev server (runs all generation scripts first) +npm run build # Build static site for production +npm run sidebars # Generate sidebars.js from MDX folder structure +npm run counters # Generate figure/table/equation counters +npm run versions # Extract version metadata +npm run report-map # Generate reportIdMap.js for document routing +npm run image-dims # Generate image dimension metadata +npm run generate-toc # Generate Event Tree Database TOC data ``` +Build scripts respect `DOCS_MODE`: `dev` (default) builds all docs including those flagged `active: false`; `prod` excludes inactive docs. `npm start` sets `dev`; `npm run build` sets `prod`. + ## Project Structure ``` @@ -20,16 +24,26 @@ docs/ # Documentation content (MDX files) ├── desktop-applications/ # LifeSim, RMC-TotalRisk, RMC-RFA, RMC-BestFit ├── toolbox-technical-manuals/ # Internal Erosion, Overtopping, Risk Calcs, Seismic ├── web-applications/ # RRFT, LST, DST -└── 00-documentation-guide/ # Contributor guide and style reference +└── dev/ # Developer-facing docs + ├── documentation-guide/ # Contributor guide and style reference + ├── github-workflows/ # GitHub workflow SOP + ├── architecture/ # Web app architecture references + ├── ai-development/ # AI-assisted development guidance + ├── python-quickstart-guide/ + └── dst/ # DST developer + UI style guides src/ ├── components/ # 40+ custom React components (Figure, Table*, Citation, etc.) -├── contexts/ # ReportIdContext for version/document tracking +├── contexts/ # ReportIdContext, TourContext ├── css/ # Tailwind & component styles -└── theme/ # Docusaurus theme customizations +├── theme/ # Docusaurus theme customizations (DocItem watermark, Layout, etc.) +├── docConfig.js # Central source of truth for active/draft flags +└── draftDocs.js # Thin shim around docConfig.js (consumed by DocItem) -scripts/ # Build automation (sidebar, counter, version generation) +scripts/ # Build automation (sidebars, counters, versions, etc.) static/ # Static assets and auto-generated metadata +.github/ # CODEOWNERS, PR template, workflows, AI review prompt +planning/ # Implementation specs for cross-cutting changes ``` ## Auto-Generated Files (DO NOT EDIT) @@ -37,10 +51,20 @@ static/ # Static assets and auto-generated metadata These files are regenerated by build scripts: - `sidebars.js` - Generated from docs/ structure - `src/reportIdMap.js` - Generated from MDX frontmatter +- `src/imageDimensions.js` - Generated from images in static/figures/ - `static/counters/` - Figure/table/equation numbering - `static/versions/` - Version metadata - `src/data/` - Event tree TOC data +## Document Active/Draft Flags + +`src/docConfig.js` is the central registry for every published document tile. Each entry has two orthogonal flags: + +- `active`: `true` means the doc is built, served, sidebar-registered, and indexed by Algolia. `false` means the doc is excluded from the prod build and renders as a "Coming Soon" tile on the landing page; in dev (`DOCS_MODE=dev`) it still builds so contributors can work on it. +- `draft`: `true` renders a diagonal "DRAFT" watermark on the **latest version only** of the doc (older versions stay unwatermarked). `false` means no watermark. + +The two flags are orthogonal — a doc can be `active: true, draft: true` (published with watermark) or `active: false, draft: true` (unpublished but flagged for future watermarking). + ## Key Patterns ### MDX Document Structure @@ -78,6 +102,26 @@ Content with
- Version paths: `docs/{category}/{app}/{type}/v{major}.{minor}/` - Special files: `00-document-info.mdx`, `00-version-history.mdx` +## Branching and Review Workflow + +The `main` branch is protected. All changes go through a pull request. Branch prefixes auto-assign the PR to one of five review lanes via the `stage-progression.yml` GitHub workflow: + +| Prefix | Lane | Reviews required | +|---|---|---| +| `docs/new/` | New document | Peer → Lead Civil → Technical edit → Director | +| `docs/major/` | Major revision (new major version) | Peer → Lead Civil | +| `docs/minor/` | Minor revision (new minor version) | Peer | +| `docs/fix/` | Editorial fix | None (admin self-merge) | +| `docs/dev/` | Dev docs (anything under `docs/dev/`) | None (admin self-merge) | + +Dev-docs detection is also content-based: any PR whose changed files under `docs/` are all under `docs/dev/` is auto-routed to `lane:dev` regardless of branch name. + +Branch protection on `main` requires two status checks: +- `CI Build` — runs `npm run build` on every PR +- `review-workflow` — set by `stage-progression.yml`; flips to success when the PR reaches `stage:ready-to-merge` (or immediately for `lane:editorial-fix` and `lane:dev`) + +Full details: [docs/dev/documentation-guide/](docs/dev/documentation-guide/) chapters 09–15. + ## Code Style - Prettier: 150 char line width, single quotes, trailing commas @@ -89,25 +133,9 @@ Content with
- Do NOT include "Co-Authored-By: Claude", "Claude Code", or any AI/assistant attribution in commit messages - Keep commit messages concise and focused on the changes made -## Claude Code Skills - -This repository includes Claude Code skills (slash commands) in `.claude/skills/`. Reference files for skills are in `.claude/skills/*.md` (e.g., `git-conventions.md`). - -### Available Skills - -**Git**: `/commit`, `/push`, `/commit-push`, `/pr`, `/review-pr` -**Page verification**: `/smoke-test`, `/review-responsive`, `/review-page` -**Quality**: `/check-accessibility`, `/check-performance`, `/lint-fix` -**Documentation**: `/qc-review`, `/build`, `/check-links`, `/check-components` -**Scaffolding**: `/new-doc` - -See `.claude/skills/{name}/SKILL.md` for full documentation of each skill. +## QC Reviews -## QC Reviews & Technical Edits - -Use `/qc-review` skill or the QC prompt template at [qc/qc-prompt.md](qc/qc-prompt.md) for AI-assisted document reviews. - -### Review Levels +The QC prompt template at [qc/qc-prompt.md](qc/qc-prompt.md) is a manually-usable template for AI-assisted document reviews. It supports three levels: | Level | Name | When to Use | |-------|------|-------------| @@ -115,13 +143,14 @@ Use `/qc-review` skill or the QC prompt template at [qc/qc-prompt.md](qc/qc-prom | 2 | Source Comparison | Source PDF available; Level 1 + verify MDX matches source exactly | | 3 | Technical Edit | Source PDF available; Levels 1 & 2 + suggest content improvements | -### Key Rules - +Key rules: - **Level 1**: Do NOT suggest rewording or technical changes—syntax and grammar only - **Level 2**: Do NOT suggest improvements beyond matching the source document - **Level 3**: Full editorial suggestions allowed; mark these as "Editorial" category with "Suggestion" severity - All levels: Do NOT edit MDX files directly—output findings to `qc/` only +The standardized prompt for the formal in-PR technical edit is at [.github/ai-review/technical-editor-prompt.md](.github/ai-review/technical-editor-prompt.md) — see Documentation Guide chapter 13 for how it's invoked. + ## Requirements - Node.js >= 18.0 diff --git a/docs/dev/documentation-guide/09-appendix-a-source-code-structure.mdx b/docs/dev/documentation-guide/16-appendix-a-source-code-structure.mdx similarity index 100% rename from docs/dev/documentation-guide/09-appendix-a-source-code-structure.mdx rename to docs/dev/documentation-guide/16-appendix-a-source-code-structure.mdx diff --git a/docs/dev/documentation-guide/10-appendix-b-build-process-overview.mdx b/docs/dev/documentation-guide/17-appendix-b-build-process-overview.mdx similarity index 100% rename from docs/dev/documentation-guide/10-appendix-b-build-process-overview.mdx rename to docs/dev/documentation-guide/17-appendix-b-build-process-overview.mdx diff --git a/docs/dev/documentation-guide/11-appendix-c-search-configuration.mdx b/docs/dev/documentation-guide/18-appendix-c-search-configuration.mdx similarity index 100% rename from docs/dev/documentation-guide/11-appendix-c-search-configuration.mdx rename to docs/dev/documentation-guide/18-appendix-c-search-configuration.mdx From de2641fe95c8de535bebcc1e786e22ccc696f99c Mon Sep 17 00:00:00 2001 From: Adam Gohs Date: Tue, 19 May 2026 10:15:36 -0400 Subject: [PATCH 2/7] Fix Documentation Guide gaps for branching and docConfig.js - 02-versioning-system Step 7: replace direct-to-main push with the branch-and-PR flow that branch protection on main requires; explain docs/major and docs/minor branch prefixes - 03-project-structure: add src/docConfig.js as a Tier 1 contributor-edit file with full description of active/draft flag semantics; note that src/draftDocs.js is now a shim - 16-appendix-a (Source Code): rewrite the draftDocs section to describe docConfig.js as the source of truth; replace the outdated DocItem code example with the current version-aware watermark implementation --- .../02-versioning-system.mdx | 60 +++++---- .../03-project-structure.mdx | 46 +++++++ .../16-appendix-a-source-code-structure.mdx | 124 ++++++++++++------ 3 files changed, 166 insertions(+), 64 deletions(-) diff --git a/docs/dev/documentation-guide/02-versioning-system.mdx b/docs/dev/documentation-guide/02-versioning-system.mdx index ee78084ee..91a79cce3 100644 --- a/docs/dev/documentation-guide/02-versioning-system.mdx +++ b/docs/dev/documentation-guide/02-versioning-system.mdx @@ -271,7 +271,12 @@ All necessary scripts run automatically during `npm start` or `npm run build`. Y - Test cross-references - Verify bibliography displays correctly (if applicable) -### Step 7: Commit Changes +### Step 7: Commit Changes and Open a Pull Request + +The `main` branch is protected — changes cannot be pushed directly. All revisions are committed to a feature branch and merged via a pull request. The branch prefix routes the PR to the appropriate review lane (see [Review Lanes](./10-review-lanes.mdx)): + +- **Major revision** (e.g., `v1.0` → `v2.0`): use prefix `docs/major/` +- **Minor revision** (e.g., `v1.0` → `v1.1`): use prefix `docs/minor/` +

✅ Create a Branch

+
    +
  1. In GitHub Desktop, click the Current Branch dropdown
    2. +
  2. Click New Branch
    3. +
  3. Name the branch using the appropriate prefix (e.g., docs/minor/lifesim-users-guide-v1.1)
    4. +
  4. Confirm the branch is created from main
    5. +
  5. Click Create Branch
    6. +

✅ Stage and Commit Changes

    -
  1. Open GitHub Desktop
    2. -
  2. You should see all changed files listed in the left sidebar under "Changes"
    3. +
  3. Changed files appear in the left sidebar under "Changes"
  4. Review the changes in the diff viewer on the right
  5. Enter a commit message in the Summary field (e.g., "Add v1.1 documentation with updated usage guide")
  6. Optionally add a more detailed Description
    7. -
  7. Click Commit to main (or your current branch)
    8. +
  8. Click Commit to docs/minor/...
-

✅ Push Changes to Remote

+

✅ Push Changes and Open the PR

    -
  1. After committing, click Push origin in the top toolbar
    2. -
  2. Your changes will be uploaded to the GitHub repository
    3. +
  3. Click Publish branch (first push) or Push origin (subsequent pushes)
    4. +
  4. Click Create Pull Request — this opens the GitHub website to the PR creation page
    5. +
  5. Fill in the PR description, assign a peer reviewer if known, and click Create pull request
), @@ -302,25 +315,28 @@ All necessary scripts run automatically during `npm start` or `npm run build`. Y value: 'git', child: ( <> -

✅ Stage, Commit, and Push Changes

- 
{`# Stage all changes
-git add .
-
-# Commit with descriptive message
+          
✅ Create a Branch, Commit, and Push

+          
{`# Create and switch to a new branch off main
+git checkout main
+git pull origin main
+git checkout -b docs/minor/lifesim-users-guide-v1.1
 
+# Stage and commit
+git add .
 git commit -m "Add v1.1 documentation with updated usage guide"
 
-# Push to remote
-
-git push origin main`}

-
-
-),
-},
-]}
-defaultValue="github-desktop"
+# Push the branch to GitHub
+git push -u origin docs/minor/lifesim-users-guide-v1.1`}
+

Then open the PR on GitHub.com — the push output contains a link to "Create a pull request for this branch." Click it, fill in the description, and submit.

+ + ), + }, + ]} + defaultValue="github-desktop" /> +After the PR is opened, a preview build is published to an unadvertised URL and the review workflow auto-assigns a lane label. See [Author Workflow](./11-author-workflow.mdx) for what happens next. + --- ## Version Notice for Users @@ -453,4 +469,4 @@ npm start - Old versions remain accessible to users - Match software versions when documenting software releases -For more details on the build process and automation scripts, see [Appendix B: Build Process Overview](./10-appendix-b-build-process-overview.mdx). +For more details on the build process and automation scripts, see [Appendix B: Build Process Overview](./17-appendix-b-build-process-overview.mdx). diff --git a/docs/dev/documentation-guide/03-project-structure.mdx b/docs/dev/documentation-guide/03-project-structure.mdx index 0fc3dd289..5453d33d4 100644 --- a/docs/dev/documentation-guide/03-project-structure.mdx +++ b/docs/dev/documentation-guide/03-project-structure.mdx @@ -37,6 +37,8 @@ RMC-SOFTWARE-DOCUMENTATION/ │ ├── theme/ ⛔ DON'T TOUCH - Docusaurus theme overrides │ ├── pages/ ⛔ DON'T TOUCH - Landing pages │ ├── data/ ⛔ DON'T TOUCH - Auto-generated +│ ├── docConfig.js ✅ YOU EDIT THIS - Document active/draft flags +│ ├── draftDocs.js ⛔ DON'T TOUCH - Thin shim around docConfig.js │ ├── imageDimensions.js ⛔ DON'T TOUCH - Auto-generated │ └── reportIdMap.js ⛔ DON'T TOUCH - Auto-generated ├── scripts/ ⛔ DON'T TOUCH - Build automation @@ -425,6 +427,49 @@ Bibliography files must be created **before** building the documentation. If ref --- +### `src/docConfig.js` - Document Active/Draft Registry + +**Purpose:** Central source of truth for which documents are published on the site and which display the DRAFT watermark. + +This is the **only file in `src/` that contributors edit directly**. Every other file under `src/` is auto-generated or restricted to administrators. + +**Structure:** + +Each document tile on a category landing page corresponds to one entry in the `docs` array. Each entry has two orthogonal flags: + +```javascript +{ + category: 'desktop-applications', + software: 'lifesim', + doc_location: 'desktop-applications/lifesim/users-guide', + doc_name: 'LifeSim Users Guide', + active: true, // Built, served, sidebar-registered, and search-indexed + draft: false, // No DRAFT watermark +}, +``` + +**The `active` flag** controls whether the document is included in the production build: + +- `active: true` — the document is built, served at its URL, added to the sidebar, and indexed by the search crawler. +- `active: false` — the document is excluded from the production build. The landing page renders a "Coming Soon" tile instead. In dev (`npm start`), the document still builds so contributors can work on it without exposing it publicly. + +**The `draft` flag** controls the watermark only: + +- `draft: true` — a large diagonal "DRAFT" watermark renders on the **latest version** of the document. Older versions are not watermarked. +- `draft: false` — no watermark. + +The two flags are independent. A document can be `active: true, draft: true` (published but flagged as draft) or `active: false, draft: true` (unpublished and flagged for watermarking when later activated). + +**When to edit:** + +- **Registering a new document:** add a new entry with `active: false, draft: true` while the document is being authored. Flip `active: true` when the site administrator publishes it. +- **Publishing a draft as final:** flip `draft: false` on the entry. This happens as part of the merge that completes a review (see [Site Admin Workflow](./15-site-admin-workflow.mdx)). +- **Renaming or removing a document:** edit or delete the entry. + +**Download-only entries** (entries with a `downloadUrl` and no `doc_location`) link directly to a PDF and are unaffected by the active/draft build-inclusion logic. Use these for technical reference manuals served as PDFs rather than as MDX-built pages. + +--- + ### `static/source-documents/` - Original Source Files **Purpose:** Store original Word documents, PDFs, and other source materials. @@ -855,6 +900,7 @@ Common auto-generated files: - Images in `static/figures/` - Citation files in `static/bibliographies/` - Source documents in `static/source-documents/` +- `src/docConfig.js` to register new documents or flip active/draft flags ### 📖 Read and Reference diff --git a/docs/dev/documentation-guide/16-appendix-a-source-code-structure.mdx b/docs/dev/documentation-guide/16-appendix-a-source-code-structure.mdx index f0c04a585..78c689b6e 100644 --- a/docs/dev/documentation-guide/16-appendix-a-source-code-structure.mdx +++ b/docs/dev/documentation-guide/16-appendix-a-source-code-structure.mdx @@ -34,7 +34,8 @@ src/ ├── data/ → Build-generated data files ├── pages/ → Custom web pages (homepage, landing pages) ├── theme/ → Docusaurus theme overrides -├── draftDocs.js → Draft document tracking +├── docConfig.js → Central document active/draft registry +├── draftDocs.js → Thin shim around docConfig.js ├── imageDimensions.js → Auto-generated image metadata └── reportIdMap.js → Auto-generated ID mappings ``` @@ -527,29 +528,57 @@ npm run swizzle @docusaurus/theme-classic ComponentName **Files:** `src/theme/DocItem/index.js`, `src/theme/DocItem/Layout/index.js`, `src/theme/DocItem/Layout/styles.module.css` -**Purpose:** Override the default documentation page wrapper to add DRAFT watermark functionality and custom layout styles. +**Purpose:** Override the default documentation page wrapper to add a version-aware DRAFT watermark and custom layout styles. **Custom Functionality:** -- Checks if current document is marked as `draft: true` in front matter -- Applies watermark overlay for draft documents +- Reads the current page's pathname and matches it against the `draftDocs` list (which is derived from `src/docConfig.js`) +- Cross-references the version in the URL against `latestVersions.json` so the watermark only renders on the **latest** version of a flagged document — older versions of the same document stay unwatermarked - Preserves all default DocItem behavior **How It Works:** ```javascript -import { useDoc } from '@docusaurus/theme-common'; -import draftDocs from '@site/src/draftDocs'; +import React from 'react'; +import DocItem from '@theme-original/DocItem'; +import { useLocation } from '@docusaurus/router'; +import { draftDocs } from '../../draftDocs'; +import latestVersions from '@site/static/versions/latestVersions.json'; + +function getDocInfo(pathname) { + const stripped = pathname + .replace(/^\/RMC-Software-Documentation\/docs\//, '') + .replace(/^\/docs\//, '') + .replace(/^docs\//, ''); + const match = stripped.match(/^(.+?)\/(v\d+\.\d+(?:\.\d+)?)(?:\/|$)/); + if (!match) return null; + return { docBasePath: match[1], version: match[2] }; +} -export default function DocItem(props) { - const { metadata } = useDoc(); - const isDraft = draftDocs.includes(metadata.id); +function isDraftDoc(pathname) { + const info = getDocInfo(pathname); + if (!info) return false; + const isFlagged = draftDocs.some( + (base) => info.docBasePath === base || info.docBasePath.startsWith(base + '/') + ); + if (!isFlagged) return false; + const latest = latestVersions[info.docBasePath]; + if (!latest) return true; + return info.version === latest; +} +export default function DocItemWrapper(props) { + const location = useLocation(); + const showWatermark = isDraftDoc(location.pathname); return ( -
- {isDraft && } - -
+ <> + {showWatermark && ( +
+ DRAFT +
+ )} + + ); } ``` @@ -571,7 +600,7 @@ export default function DocItem(props) { - Algolia credentials in `docusaurus.config.js` - Custom search styling in component -- See [Appendix C: Search Configuration](./11-appendix-c-search-configuration.mdx) +- See [Appendix C: Search Configuration](./18-appendix-c-search-configuration.mdx) ### Creating New Theme Overrides @@ -594,44 +623,51 @@ Only swizzle theme components if absolutely necessary. Theme overrides can break --- -## draftDocs.js +## docConfig.js and draftDocs.js -**Location:** `src/draftDocs.js` +**Location:** `src/docConfig.js` and `src/draftDocs.js` -**Purpose:** Aggregates all documents marked with `draft: true` in their front matter and exports an array of draft document IDs. +`src/docConfig.js` is the **central source of truth** for which documents are published and which display the DRAFT watermark. Every published document tile has exactly one entry in the `docs` array with two orthogonal flags: -**Generated By:** Build process (may be manual or scripted) +```javascript +{ + category: 'desktop-applications', + software: 'lifesim', + doc_location: 'desktop-applications/lifesim/users-guide', + doc_name: 'LifeSim Users Guide', + active: true, // controls build inclusion, sidebar, and search + draft: false, // controls watermark only +}, +``` -**Used By:** `DocItem` theme component to determine whether to display DRAFT watermark +The file is CommonJS so both the React app (for landing-page tile rendering) and Node build scripts (for sidebar generation, version metadata, build exclusion) can consume it from the same source. It also exports three helper functions: -**Example Structure:** +- `filterByCategoryAndSoftware(category, software)` — used by landing pages to filter the doc list +- `getInactiveDocLocations()` / `getDraftDocLocations()` — used by build scripts +- `shouldExcludeFromBuild(docsRelativePath)` — used by `scripts/generateSidebars.js` and `scripts/versions.js` to skip inactive docs in prod builds -```javascript -// draftDocs.js -const draftDocs = [ - 'lifesim/v1.0/05-advanced-features', - 'watersim/v2.0/03-calibration', - // ...more draft document IDs -]; - -export default draftDocs; -``` +**Active vs. draft semantics:** -**How Documents Are Identified:** +- `active: true` → doc is built, served, sidebar-registered, and indexed by the search crawler. +- `active: false` → doc is excluded from the prod build (no static HTML, no sidebar, no Algolia entry); landing page renders a "Coming Soon" tile. In dev (`DOCS_MODE !== 'prod'`), the doc is built so contributors can work on it without exposing it publicly. +- `draft: true` → DRAFT watermark renders on the **latest version** of the doc only. +- `draft: false` → no watermark. -- Document with front matter `draft: true` gets added to array -- Array contains base paths (no file extension) -- Theme component checks if current page matches any draft path +The two flags are orthogonal. A doc may be `active+draft` (published with watermark, fully searchable) or `inactive+draft` (unpublished, watermark configured for whenever it goes active). -**Updating Draft List:** +**Download-only entries** — entries with a `downloadUrl` but no `doc_location` — link directly to a PDF and are unaffected by the build-inclusion logic. -Depending on implementation, this may be: +**`src/draftDocs.js`** is a thin shim that imports `getDraftDocLocations()` and exports the resulting array of doc locations. It exists because `src/theme/DocItem/index.js` needs a clean ESM-style import for the client-side watermark check, while `docConfig.js` is consumed via `require()` from build scripts. Concretely: -- Auto-generated during build -- Manually updated by site administrators -- Generated by a dedicated script +```javascript +// src/draftDocs.js +import { getDraftDocLocations } from './docConfig'; +export const draftDocs = getDraftDocLocations(); +``` -Check with site maintainers for the specific update process. +**Updating the list:** + +Edit `src/docConfig.js` directly — flip `active` or `draft` on the relevant entry, or add a new entry for a new document. The file is checked into version control and is not auto-generated. --- @@ -882,7 +918,11 @@ The `src/` folder contains the technical foundation of the RMC Software Document - `reportIdMap.js` - Document ID mappings - `imageDimensions.js` - Image dimension metadata -- `draftDocs.js` - Draft document tracking (may be manual) + +**Contributor-Edited Files:** + +- `docConfig.js` - Central registry of active/draft flags for every document tile +- `draftDocs.js` - Thin shim around `docConfig.js` consumed by the DocItem theme component **Important Principles:** @@ -894,7 +934,7 @@ The `src/` folder contains the technical foundation of the RMC Software Document **For More Information:** - Component usage: [React Components Reference](./07-react-components.mdx) -- Build process: [Appendix B: Build Process Overview](./10-appendix-b-build-process-overview.mdx) +- Build process: [Appendix B: Build Process Overview](./17-appendix-b-build-process-overview.mdx) - Project structure: [Project Structure](./03-project-structure.mdx) --- From 6283c973afaf6315bff70feea1f9002db7bf993c Mon Sep 17 00:00:00 2001 From: Adam Gohs Date: Tue, 19 May 2026 10:15:46 -0400 Subject: [PATCH 3/7] Add seven review-process chapters to Documentation Guide Adds chapters 09-15 covering the review and approval workflow: 09. Review and Approval Process Overview 10. Review Lanes 11. Author Workflow 12. Reviewer Workflow 13. Technical Edit (includes the full AI prompt verbatim) 14. Director Workflow 15. Site Admin Workflow Companion changes: - Update generateSidebars.js mainIds/appendixIds for new chapter numbering - Update 00-introduction guide-organization and Common Contribution Workflows sections to reference new chapters and branch prefixes - Update appendix B cross-link in 01-getting-started for the rename The three appendices were renamed 09/10/11 -> 16/17/18 in the prior commit because the renames were already staged via git mv. URLs are unchanged since Docusaurus strips numeric prefixes. --- .../documentation-guide/00-introduction.mdx | 81 ++++++---- .../01-getting-started.mdx | 2 +- .../09-review-and-approval-overview.mdx | 67 +++++++++ .../documentation-guide/10-review-lanes.mdx | 84 +++++++++++ .../11-author-workflow.mdx | 88 +++++++++++ .../12-reviewer-workflow.mdx | 61 ++++++++ .../documentation-guide/13-technical-edit.mdx | 130 +++++++++++++++++ .../14-director-workflow.mdx | 48 ++++++ .../15-site-admin-workflow.mdx | 138 ++++++++++++++++++ scripts/generateSidebars.js | 9 +- 10 files changed, 675 insertions(+), 33 deletions(-) create mode 100644 docs/dev/documentation-guide/09-review-and-approval-overview.mdx create mode 100644 docs/dev/documentation-guide/10-review-lanes.mdx create mode 100644 docs/dev/documentation-guide/11-author-workflow.mdx create mode 100644 docs/dev/documentation-guide/12-reviewer-workflow.mdx create mode 100644 docs/dev/documentation-guide/13-technical-edit.mdx create mode 100644 docs/dev/documentation-guide/14-director-workflow.mdx create mode 100644 docs/dev/documentation-guide/15-site-admin-workflow.mdx diff --git a/docs/dev/documentation-guide/00-introduction.mdx b/docs/dev/documentation-guide/00-introduction.mdx index 4509a4df9..08daaf7f5 100644 --- a/docs/dev/documentation-guide/00-introduction.mdx +++ b/docs/dev/documentation-guide/00-introduction.mdx @@ -137,11 +137,21 @@ The documentation guide is structured to take you from setup through advanced us 8. **[Troubleshooting & FAQ](./08-troubleshooting-faq.mdx)** - Solutions to common problems +### Review and Approval Process + +9. **[Review and Approval Process Overview](./09-review-and-approval-overview.mdx)** - Roles, lanes, the merge gate, and the draft watermark +10. **[Review Lanes](./10-review-lanes.mdx)** - Branch prefixes and which review stages apply to each lane +11. **[Author Workflow](./11-author-workflow.mdx)** - From branch creation to publication +12. **[Reviewer Workflow](./12-reviewer-workflow.mdx)** - For peer reviewers and RMC Lead Civils +13. **[Technical Edit](./13-technical-edit.mdx)** - AI-assisted editorial review (includes the full prompt) +14. **[Director Workflow](./14-director-workflow.mdx)** - Final approval for new documents +15. **[Site Admin Workflow](./15-site-admin-workflow.mdx)** - Reviewer assignment, checkpoint deploys, merge prep + ### Appendices (Advanced Topics) -- **[Appendix A: Source Code Structure](./09-appendix-a-source-code-structure.mdx)** - Deep dive into project architecture -- **[Appendix B: Build Process Overview](./10-appendix-b-build-process-overview.mdx)** - How automation scripts work behind the scenes -- **[Appendix C: Search Configuration](./11-appendix-c-search-configuration.mdx)** - Algolia search setup (admin-level) +- **[Appendix A: Source Code Structure](./16-appendix-a-source-code-structure.mdx)** - Deep dive into project architecture +- **[Appendix B: Build Process Overview](./17-appendix-b-build-process-overview.mdx)** - How automation scripts work behind the scenes +- **[Appendix C: Search Configuration](./18-appendix-c-search-configuration.mdx)** - Algolia search setup (admin-level) --- @@ -258,20 +268,24 @@ This is regular text with **bold** and _italic_ formatting. ## Common Contribution Workflows +The `main` branch is protected. Every change goes through a feature branch and a pull request. The branch prefix routes the PR to one of five review lanes — see [Review Lanes](./10-review-lanes.mdx) for the full mapping. + ### Workflow 1: Convert Existing Word Document **Use case:** You have an existing RMC document in Word format that needs to be converted to MDX. **Steps:** -1. Place Word document in `static/source-documents/` -2. Run DOCX converter script to generate MDX files -3. Review and refine generated MDX files -4. Add generated files to appropriate `docs/` folder -5. Test locally with `npm start` -6. Commit changes to Git +1. Create a `docs/new/` branch off `main`. +2. Place the Word document in `static/source-documents/`. +3. Run the DOCX converter script to generate MDX files. +4. Review and refine generated MDX files. +5. Add generated files to the appropriate `docs/` folder. +6. Register the document in `src/docConfig.js` with `active: false, draft: true`. +7. Test locally with `npm start`. +8. Commit, push the branch, and open a pull request. The review workflow auto-assigns Lane 1 (peer → Lead Civil → technical edit → Director). -**Typical time:** 1-3 hours depending on document complexity +**Typical time:** 1-3 hours depending on document complexity. --- @@ -283,19 +297,20 @@ This is regular text with **bold** and _italic_ formatting. For a detailed, step-by-step guide to creating a new document from scratch, see [Chapter 04: Creating a New Document - Complete Walkthrough](./04-creating-new-document-walkthrough.mdx). -The walkthrough includes folder setup, asset organization, administrator coordination, testing procedures, and complete examples. +The walkthrough includes folder setup, asset organization, testing procedures, and complete examples. ::: **High-Level Steps:** -1. Determine folder location based on hierarchy (see [Complete Walkthrough](./04-creating-new-document-walkthrough.mdx)) -2. Create all folder structures (docs/, static/figures/, static/videos/, static/bibliographies/) -3. Add supporting assets (figures, videos, bibliography) -4. Create MDX files (using DOCX converter or manually) -5. Test locally with `npm start` -6. Contact site administrator for deployment coordination -7. Commit changes to repository after approval +1. Create a `docs/new/` branch off `main`. +2. Determine folder location based on hierarchy (see [Complete Walkthrough](./04-creating-new-document-walkthrough.mdx)). +3. Create all folder structures (`docs/`, `static/figures/`, `static/videos/`, `static/bibliographies/`). +4. Add supporting assets (figures, videos, bibliography). +5. Create MDX files (using the DOCX converter or manually). +6. Register the document in `src/docConfig.js` with `active: false, draft: true`. +7. Test locally with `npm start`. +8. Commit, push, and open a PR. The review workflow auto-assigns Lane 1 and guides you through peer → Lead Civil → technical edit → Director review (see [Author Workflow](./11-author-workflow.mdx)). **For detailed instructions, templates, real-world examples, and troubleshooting, use the [comprehensive walkthrough](./04-creating-new-document-walkthrough.mdx).** @@ -305,23 +320,27 @@ The walkthrough includes folder setup, asset organization, administrator coordin **Use case:** You need to update an existing document for a new software version or to correct errors. -**For minor edits (typos, small clarifications):** +**For typos and editorial fixes (Lane 4):** + +1. Create a `docs/fix/` branch off `main`. +2. Edit the existing version's MDX files directly. +3. Test locally. +4. Commit, push, and open a PR. The site admin will review and merge — no formal peer review required. + +**For minor revisions / new minor version (Lane 3):** -1. Edit the existing version's MDX files directly -2. Test locally -3. Commit changes +1. Create a `docs/minor/-v` branch off `main`. +2. Create the new version folder (e.g., `v1.1/`) by copying the previous version. +3. Mirror the version structure for figures, bibliography, and source documents. +4. Make your updates and flip `draft: true` on the document's entry in `src/docConfig.js`. +5. Test locally. +6. Commit, push, and open a PR. The workflow assigns Lane 3 (peer review → technical edit). -**For major updates (new features, substantial changes):** +**For major revisions / new major version (Lane 2):** -1. Create new version folders (e.g., `v1.1/`) -2. Copy all files from previous version -3. Make updates to the new version -4. Add new images to corresponding `static/figures/` version folder -5. Update `bib.json` if needed -6. Test locally -7. Commit changes +Same as Lane 3 but on a `docs/major/-v` branch. The workflow adds an RMC Lead Civil review stage between peer review and the technical edit. -**Typical time:** 30 minutes to 2 hours depending on scope +**Typical time:** 30 minutes to a few hours depending on scope. Review turnaround adds days; plan accordingly. --- diff --git a/docs/dev/documentation-guide/01-getting-started.mdx b/docs/dev/documentation-guide/01-getting-started.mdx index 0ba41a4f6..4e9e4dd70 100644 --- a/docs/dev/documentation-guide/01-getting-started.mdx +++ b/docs/dev/documentation-guide/01-getting-started.mdx @@ -278,7 +278,7 @@ This will start the development server at `http://localhost:3000`. Any changes y - Press `Ctrl+C` in the terminal :::tip Deployment is Admin-Only -Contributors should focus on creating and editing documentation content using `npm start` for local testing. Site administrators will handle all building and deployment to production. See [Appendix B: Build Process Overview](./10-appendix-b-build-process-overview.mdx) for deployment details. +Contributors should focus on creating and editing documentation content using `npm start` for local testing. Site administrators will handle all building and deployment to production. See [Appendix B: Build Process Overview](./17-appendix-b-build-process-overview.mdx) for deployment details. ::: :::tip Take the Guided Site Tour diff --git a/docs/dev/documentation-guide/09-review-and-approval-overview.mdx b/docs/dev/documentation-guide/09-review-and-approval-overview.mdx new file mode 100644 index 000000000..f936b2595 --- /dev/null +++ b/docs/dev/documentation-guide/09-review-and-approval-overview.mdx @@ -0,0 +1,67 @@ +--- +title: Review and Approval Process Overview +--- + +import NavContainer from '@site/src/components/NavContainer'; + + + +# 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 jump to the role-specific chapter that applies to you. + +## Who participates + +**Author.** Writes or revises the document. The only role that needs local development tooling — everyone else works in a web browser. + +**Peer reviewer.** Subject-matter expert assigned ad-hoc to review technical accuracy. Works entirely in the GitHub web interface, reading the document on an unadvertised preview URL. + +**RMC Lead Civil.** Provides technical oversight and quality assurance. Assigned ad-hoc per document. Works in the GitHub web interface, also reviewing on the preview URL. + +**Technical edit (AI-assisted).** An AI-powered editorial review that checks grammar, clarity, tense, terminology, and Section 508 accessibility compliance. A team member with the right tooling triggers the review, and the AI posts inline comments directly on the pull request. A human technical editor can be substituted at the site admin's discretion. + +**Director.** The RMC Director provides final approval for new documents only. Reviews the document on the live site (with a DRAFT watermark) and clicks Approve — no file editing required. + +**Site administrator.** Manages reviewer assignments, checkpoint deploys, merge preparation, and final deploys. The only role with access to protected parts of the repository. + +## The five review lanes + +Every change falls into one of five lanes based on its scope: + +**Lane 1: New document.** Peer review → Lead Civil review → Technical edit → Director approval. The peer review, Lead Civil review, and technical edit all happen against the preview URL or the source files. Only after the technical edit completes does the site admin deploy the document to the live site (watermarked) for Director review at the document's final URL. + +**Lane 2: Major revision.** Peer review → Lead Civil review. Entire review happens on the preview site. Site admin deploys the final version after Lead Civil approval. + +**Lane 3: Minor revision.** Peer review only on the preview site. + +**Lane 4: Editorial fix.** Site admin reviews and deploys directly. No formal review. + +**Lane 5: Dev docs.** Any change to documents under `docs/dev/` — developer documentation, contributor guides, internal references. Treated like Lane 4 — site admin reviews and merges directly, no formal review required. + +See [Review Lanes](./10-review-lanes.mdx) for branch-prefix conventions and detailed examples of each lane. + +## The merge gate + +Every documentation PR has a GitHub commit status called `review-workflow` that functions as the merge gate. Branch protection on `main` requires this status to be `success` before the PR can merge, so nobody — not even a site admin — can merge a PR whose review is incomplete. The stage progression workflow sets this status automatically: + +- **Pending** during any active review stage (`stage:peer-review`, `stage:lead-civil-review`, `stage:ai-editor-review`, `stage:director-review`, or `stage:needs-lane`) +- **Success** when the PR reaches `stage:ready-to-merge`, or immediately on lane assignment for `lane:editorial-fix` and `lane:dev` +- **Success** for non-docs PRs (infrastructure, tooling, dependency updates) as soon as `CI Build` passes + +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 admin's discretion. + +## The draft watermark + +Documents flagged as drafts display a large diagonal "DRAFT" watermark. For Lane 1, the watermark appears on the live site during the Director review phase only — the document is not deployed to the live site until the technical edit is complete. The watermark signals to any reader who happens to find the live URL that the content is not yet authoritative. The watermark is removed when the site admin flips the draft flag after Director approval. + +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: read [Review Lanes](./10-review-lanes.mdx), then [Author Workflow](./11-author-workflow.mdx) +- Asked to review: read [Reviewer Workflow](./12-reviewer-workflow.mdx) +- Running a technical edit: read [Technical Edit](./13-technical-edit.mdx) +- Director reviewing a new document: read [Director Workflow](./14-director-workflow.mdx) +- Site administrator: read [Site Admin Workflow](./15-site-admin-workflow.mdx) diff --git a/docs/dev/documentation-guide/10-review-lanes.mdx b/docs/dev/documentation-guide/10-review-lanes.mdx new file mode 100644 index 000000000..321a0a588 --- /dev/null +++ b/docs/dev/documentation-guide/10-review-lanes.mdx @@ -0,0 +1,84 @@ +--- +title: Review Lanes +--- + +import NavContainer from '@site/src/components/NavContainer'; + + + +# Review Lanes + +Every change follows one of five review lanes. The workflow assigns a lane automatically using two signals, in order: + +1. **Content-based detection.** If every documentation file changed in the PR is under `docs/dev/`, the PR is assigned `lane:dev` regardless of branch name. +2. **Branch-name detection.** Otherwise, the branch prefix determines the lane: + +| Branch prefix | Lane | +|---|---| +| `docs/new/` | New document | +| `docs/major/` | Major revision | +| `docs/minor/` | Minor revision | +| `docs/fix/` | Editorial fix | +| `docs/dev/` | Dev docs | + +**Any PR that touches files under `docs/` is processed by the review workflow**, even if its branch name doesn't start with `docs/`. This means a collaborator can accidentally push a documentation change on a branch named `feature/typo-fix` and the workflow will still intercept it at PR open time and ask a site admin to assign a lane. Non-documentation PRs (branches that don't touch anything under `docs/`) are silently ignored by the lane workflow and go straight to the merge button once their build passes. + +If a branch starts with `docs/` but doesn't match one of the five sub-prefixes above (for example, a typo like `docs/newfoo/` or an old-style name like `docs/update`), the workflow applies `stage:needs-lane` and tags a site admin to assign the correct lane manually. The same happens for a PR that touches documentation from a non-`docs/` branch when content-based dev detection doesn't apply. + +A site admin can always override the automatically-detected lane by swapping the `lane:*` label on the PR. The workflow treats a manually-applied lane label the same as an auto-detected one and proceeds normally from there. + +## Lane 1: New document + +**When to use.** Any completely new document being added to the site. + +**Required reviews.** Peer review → RMC Lead Civil review → Technical edit (AI-assisted) → Director approval. + +**What happens.** The document is first visible only on the unadvertised PR preview URL, where peer review, Lead Civil review, and the technical edit all happen. The technical edit reads the source MDX directly and posts inline comments — it does not need a deployed version. Only after the author marks the technical edit complete does the site admin deploy the PR branch to the live production site with the DRAFT watermark. The Director then reviews on the live URL. After Director approval, the site admin flips the draft flag, merges the PR, and deploys the final version — removing the watermark. + +**Example branches:** `docs/new/totalrisk-applications-guide`, `docs/new/lifesim-validation-oroville` + +## Lane 2: Major revision + +**When to use.** Substantial changes to an existing document warranting a new major version (e.g., v1.0 → v2.0). + +**Required reviews.** Peer review → RMC Lead Civil review → Technical edit (AI-assisted). + +**What happens.** The entire review happens on the preview URL. The old version stays live and unwatermarked. After the technical edit comments are addressed, the site admin flips the draft flag, merges, and deploys. The new version becomes the default; the old version remains accessible via direct URL. + +**Example branches:** `docs/major/bep-progression-v2.0` + +## Lane 3: Minor revision + +**When to use.** Smaller updates warranting a minor version bump (e.g., v1.0 → v1.1). + +**Required reviews.** Peer review → Technical edit (AI-assisted). + +**What happens.** Same as Lane 2 but without Lead Civil review. + +**Example branches:** `docs/minor/bep-progression-v1.1` + +## Lane 4: Editorial fix + +**When to use.** Typos, broken links, grammatical corrections that don't change technical meaning. + +**Required reviews.** None. Site admin reviews and merges directly. + +**No version change, no watermark.** + +**Example branches:** `docs/fix/bep-progression-typos` + +## Lane 5: Dev docs + +**When to use.** Any new or revised document under `docs/dev/` — developer documentation, contributor guides, internal references, planning documents, and similar materials. + +**Required reviews.** None. Site admin reviews and merges directly, same as Lane 4. + +**Automatic assignment.** The workflow uses content-based detection: if every documentation file changed in the PR is under `docs/dev/`, the PR is assigned `lane:dev` regardless of what the branch is called. This means dev docs can be authored on any branch prefix (including non-`docs/` branches) and still end up in the correct lane. + +**No version change, no watermark.** + +**Example branches:** `docs/dev/ai-development-guide`, `feature/update-contributor-guide` (content detected under `docs/dev/`) + +## Choosing the right lane + +When in doubt, choose the more conservative lane. A site admin can reassign lanes by swapping `lane:*` labels. diff --git a/docs/dev/documentation-guide/11-author-workflow.mdx b/docs/dev/documentation-guide/11-author-workflow.mdx new file mode 100644 index 000000000..f4acfb8df --- /dev/null +++ b/docs/dev/documentation-guide/11-author-workflow.mdx @@ -0,0 +1,88 @@ +--- +title: Author Workflow +--- + +import NavContainer from '@site/src/components/NavContainer'; + + + +# Author Workflow + +What the 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](./10-review-lanes.mdx) for the mapping. + +**For a new document (Lane 1):** + +1. Create a `docs/new/` branch off `main`. +2. Create the directory structure under `docs/` with a `v1.0/` folder. +3. Add boilerplate MDX files following the [Project Structure](./03-project-structure.mdx) conventions. +4. Register the new document in `src/docConfig.js` with `active: false, draft: true` so it's hidden from the prod build and watermarked once activated. + +**For a revision (Lanes 2 and 3):** + +1. Create a `docs/major/-` or `docs/minor/-` branch off `main`. +2. Copy the current version folder to the new version (e.g., `cp -r v1.0/ v1.1/`). +3. Mirror the version folder for figures, bibliography, and source documents under `static/figures/`, `static/bibliographies/`, and `static/source-documents/`. +4. Flip `draft: true` on the document's entry in `src/docConfig.js`. +5. Add a placeholder row to `00-version-history.mdx`. + +**For an editorial fix (Lane 4):** + +1. Create a `docs/fix/` branch off `main`. +2. Edit the file directly. No version change. + +**For a dev doc (Lane 5):** + +1. Create a branch (`docs/dev/` prefix recommended but not required — content-based detection routes any PR whose files are all under `docs/dev/` to Lane 5). +2. Edit files under `docs/dev/`. + +All steps can be done 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 + +Open a PR via the GitHub web interface or your IDE's PR integration. The repository ships a PR template that prefills a description structure — fill in the sections (Description, Affected documents, Related issues, Pre-submission checklist, and the Technical edit checkbox for Lane 1). Assign your peer reviewer in the Reviewers sidebar if you know who it should be; otherwise the site admin will assign one. + +Within minutes, two bot comments appear on the PR: a preview URL and a stage progression comment identifying your lane. A third hidden bot comment tracks which individuals the site admin has assigned to each review stage — it renders as an "Assigned reviewers for this PR" block at the top of the PR comment thread. + +## Responding to review comments + +Reviewers post comments on specific lines in the Files changed tab. For each comment: make the fix, push a commit, reply explaining what you did. The reviewer resolves the thread when satisfied. + +For suggested changes (pre-filled code blocks), you 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 on the PR 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. + +Address each comment the same way you address human reviewer comments — push fixes, reply, and either you or the site admin can resolve threads as they're addressed. + +**When you've addressed all technical edit comments,** check the checkbox in the PR description: + +`- [x] Technical edit comments addressed — ready for Director review` + +Checking this box is what advances the document to the next stage (Director review for Lane 1, ready-to-merge for Lanes 2 and 3). Don't check it until you've addressed all comments. + +See [Technical Edit](./13-technical-edit.mdx) for the full prompt the AI uses and the alternative human-editor path. + +## Where reviewers read your document + +**Lane 1.** Peer review and Lead Civil review happen on the **preview URL**. The technical edit reads the source MDX directly and posts inline comments on the PR — no deploy is involved. Only after you mark the technical edit complete does the site admin deploy the document to the **live production site** (watermarked) for **Director review**. If you push revisions during Director review, the site admin re-deploys so the live URL stays current. + +**Lanes 2 and 3.** All review happens on the preview URL only. + +**Lanes 4 and 5.** The site admin reviews on the preview URL (if generated) or directly in the Files changed tab, then merges. + +## When reviewers ask for changes + +Reviewers typically submit their feedback as a **Comment** review (not "Request changes"), leaving inline notes on specific lines. Address each comment, push a new commit, and reply to the thread explaining what you did. You don't need to do anything else — the stage progression bot automatically pings the assigned reviewer(s) on your PR to come back and backcheck. + +**The stage does not reset when you push new commits.** A revision during peer review is for the peer reviewer to backcheck; it does not send the document back to start. Same for Lead Civil review and Director review. This is intentional — you're building on the review that already happened, not starting over. + +## When the review is complete + +The site admin prepares the merge: flips the draft flag in `src/docConfig.js`, updates the version history, merges the PR, and approves the final deploy. You'll see email notifications as this happens. Once the deploy completes, your document is live. diff --git a/docs/dev/documentation-guide/12-reviewer-workflow.mdx b/docs/dev/documentation-guide/12-reviewer-workflow.mdx new file mode 100644 index 000000000..315b9c0b6 --- /dev/null +++ b/docs/dev/documentation-guide/12-reviewer-workflow.mdx @@ -0,0 +1,61 @@ +--- +title: Reviewer Workflow +--- + +import NavContainer from '@site/src/components/NavContainer'; + + + +# Reviewer Workflow + +What peer reviewers and RMC Lead Civils do when assigned to review a documentation pull request. Written for someone with little GitHub experience. Everything can be done from a web browser. + +## Prerequisites + +You need a GitHub account and membership in the `usace-rmc` organization. A site administrator will send you an invitation — click the link in the email to accept. + +## Receiving a review request + +GitHub emails you with subject "You were requested to review [title]." Click the link to open the PR. + +## Where to read the document + +**Both peer reviewers and Lead Civils review on the preview URL.** In the PR's comment thread, look for a bot comment that says "Preview deployed" with a URL. Click it. This opens the rendered document on an unadvertised preview site with a DRAFT watermark. + +Read the document as you would any web page. This is where your review happens — you are reading, not editing. + +**Peer reviewers:** Focus on technical accuracy. Are claims correct? Equations right? Procedures complete? + +**Lead Civils:** Focus on technical quality and oversight. Does the document meet RMC standards? Is the scope appropriate? Are conclusions defensible? + +## Leaving feedback + +Click the **Files changed** tab on the PR. Hover over a line to see the blue "+" icon. Click it to open a comment box. + +**Plain comment:** Type your feedback and click "Start a review" (first comment) or "Add review comment" (subsequent). + +**Suggested change:** Click the "±" icon in the comment toolbar. Edit the pre-filled code block to your proposed wording. The author can accept your suggestion with one click. + +## Submitting your review + +Click **Finish your review** (upper right of Files changed). Choose: + +- **Comment** — you've left notes for the author to address. Use this for every review round where you have feedback. The stage does not advance. +- **Approve** — you're satisfied with the document, typically on a backcheck round after the author has addressed your prior comments. **This is what advances the stage.** +- **Request changes** — _not used in this workflow._ Use **Comment** for routine revision cycles. + +Click **Submit review.** + +The typical cycle: you leave notes via **Comment**, the author addresses them and pushes revisions, the stage progression bot pings you to backcheck, and you return to submit **Approve** if satisfied (or another **Comment** review if more feedback is needed). + +## After you approve + +The stage progression workflow advances the PR automatically **if you were the reviewer the site admin assigned for the current stage**. The workflow uses per-individual gating: it compares the approver's username to the list of reviewers the admin assigned via the Reviewers sidebar, and only advances the stage when one of those assigned reviewers approves. If you approve a PR you weren't explicitly assigned to, the bot posts a note acknowledging your approval but doesn't advance the stage. + +If the site admin assigned multiple people at the same stage, the first approval from any of them advances the stage — you don't all need to approve. + +You don't need to do anything further unless someone tags you with a follow-up question. + +## New commits after you approve + +If the author pushes new commits after you approve, GitHub dismisses your approval in the UI so the green checkmark disappears. The stage progression bot, however, does **not** reset the stage label — the document stays at its current review stage (e.g., `stage:peer-review`) and the bot pings you to backcheck the revisions. Take another look at the changes and submit another review: **Approve** if you're satisfied, or another **Comment** review with additional feedback. diff --git a/docs/dev/documentation-guide/13-technical-edit.mdx b/docs/dev/documentation-guide/13-technical-edit.mdx new file mode 100644 index 000000000..db83a3d8d --- /dev/null +++ b/docs/dev/documentation-guide/13-technical-edit.mdx @@ -0,0 +1,130 @@ +--- +title: Technical Edit +--- + +import NavContainer from '@site/src/components/NavContainer'; + + + +# Technical Edit + +The technical edit is an AI-assisted editorial review that checks the document for grammar, clarity, tense consistency, terminology, and Section 508 accessibility compliance. It is a required stage on Lanes 1, 2, and 3. A human technical editor can be substituted at the site admin's discretion. + +## When it happens + +The technical edit occurs after the prior technical review stage approves the PR: + +- **Lane 1** (new document): after Lead Civil approval +- **Lane 2** (major revision): after Lead Civil approval +- **Lane 3** (minor revision): after peer approval + +At this point, the document has already been reviewed for technical accuracy and (for Lanes 1 and 2) technical quality. The technical edit focuses exclusively on editorial quality and accessibility compliance, and reads the source MDX files directly — **no live deploy is needed at this stage**. The document is only deployed to the live site after the technical edit is complete, and that deploy is for the Director review phase (Lane 1 only). + +## How it works + +1. A team member with access to the AI tooling checks out the PR branch and runs the technical edit. +2. The tool reads all changed MDX files and applies a standardized review prompt committed to the repository at [`.github/ai-review/technical-editor-prompt.md`](https://github.com/USACE-RMC/RMC-Software-Documentation/blob/main/.github/ai-review/technical-editor-prompt.md). The prompt is reproduced in full at the bottom of this chapter so authors and reviewers can see exactly what the AI is being asked to check. +3. The AI posts inline review comments directly on the PR — on specific lines, with severity levels and suggested fixes — exactly like a human reviewer would. +4. The author addresses each comment: pushes fixes, replies to threads, and resolves conversations as they're addressed. +5. When all comments are addressed, the author checks the checkbox in the PR description: `Technical edit comments addressed — ready for Director review`. +6. The stage progression workflow detects the checkbox and advances the PR to the next stage. + +If the technical edit was done by a human or the author isn't available to check the box, a site admin can apply the `admin:advance-to-director` label to the PR as a manual override. The workflow removes the label and advances the stage the same as a checkbox event. + +## Severity levels + +The AI assigns one of three severity levels to each comment: + +- 🔴 **Must fix** — errors or accessibility violations (broken Section 508 compliance, factual grammar errors). +- 🟡 **Should fix** — clarity, consistency, or readability issues. +- 🔵 **Suggestion** — stylistic improvements the author may accept or decline. + +The author is expected to address all 🔴 and 🟡 comments. 🔵 suggestions are at the author's discretion — replying "leaving as-is" is a perfectly valid response. + +## What it does NOT review + +Technical accuracy is the peer reviewer's job. Domain conclusions, MDX component syntax, and frontmatter fields are out of scope. + +## Versioning the prompt + +The prompt is a versioned file in the repository at `.github/ai-review/technical-editor-prompt.md`. It can be updated over time as the team learns what the AI catches well and what it misses. Each technical-edit run that's noted in the PR can reference the prompt version used, so comments can be traced back to the exact instructions that generated them. + +## Fallback to a human editor + +A site admin can route any document to a human technical editor instead of (or in addition to) the AI review. The human editor follows the same workflow as peer reviewers and Lead Civils: they're assigned to the PR via the Reviewers sidebar, review the document on the **preview URL** (the technical edit happens before any live deploy), post comments, and submit their review. The author addresses comments the same way. The only difference is that advancement to the next stage requires the human editor to click Approve rather than the author checking the checkbox. + +## Who can run the AI review + +Anyone on the team with access to the AI tooling can run the technical edit. The output — the PR review comments — is visible to everyone on GitHub regardless of the reviewer's tooling. Only the trigger requires the tooling. + +If nobody with the tooling is available, use the human editor fallback. The site admin coordinates this. + +--- + +## The full review prompt + +The prompt below is sent to the AI verbatim. Authors who want to understand exactly what the AI will check (and what it has been instructed not to flag) should read this carefully. + +````markdown +# RMC Technical Editor Review Prompt + +You are a technical editor reviewing documentation for the U.S. Army Corps of Engineers Risk Management Center (USACE RMC). The documentation is written in MDX (Markdown with JSX) and covers dam safety, levee safety, and related risk analysis topics. + +## Audience + +Practicing dam and levee safety engineers within USACE. These are technical professionals who understand the domain — do not flag correct use of technical terminology as jargon. + +## Review criteria + +### Grammar and mechanics +- Spelling, punctuation, and sentence structure +- Subject-verb agreement +- Correct use of hyphens, em dashes, and en dashes +- Consistent serial comma usage + +### Tense and voice +- Prefer third-person active voice for procedures and descriptions +- Flag passive voice when active would be clearer +- Flag inconsistent tense within a section + +### Clarity and concision +- Flag wordy passages that could be shortened without losing meaning +- Flag ambiguous pronouns or unclear referents +- Flag sentences over 40 words that could be split +- Flag buried leads — key information at the end of a long sentence + +### Terminology consistency +- Flag inconsistent use of terms within the document (e.g., alternating between "embankment" and "dam" when referring to the same structure) +- Do NOT flag correct domain terminology as errors + +### Section 508 accessibility compliance +- Every image must have alt text (check for `alt=` attribute) +- Heading hierarchy must not skip levels (e.g., h2 followed by h4 without h3) +- Link text must be descriptive (flag "click here" or "link" as link text) +- Tables must have header rows +- Lists must use proper markdown list syntax, not manual numbering with plain text +- Color must not be the sole means of conveying information + +### Style consistency +- Figure and table captions must follow a consistent format +- Citations must use the site's citation key format +- Units should be consistent within each document (metric or imperial, not mixed) +- Acronyms must be defined on first use within each chapter + +## Output format + +For each finding, produce: +- The file path and line number(s) +- A severity level: 🔴 Must fix (errors, accessibility violations), 🟡 Should fix (clarity, consistency issues), 🔵 Suggestion (stylistic improvements) +- A clear description of the issue +- A suggested fix where possible (use GitHub suggestion block format) + +## What NOT to flag +- Correct use of technical terminology, even if uncommon +- MDX component syntax (imports, JSX elements) +- Frontmatter fields +- Matters of technical judgment or domain accuracy (that is the peer reviewer's job) +- Alternative phrasings that are equally acceptable +```` + +If you want to propose changes to the prompt — for example, adding a new style rule the AI has been missing — open a PR against [`.github/ai-review/technical-editor-prompt.md`](https://github.com/USACE-RMC/RMC-Software-Documentation/blob/main/.github/ai-review/technical-editor-prompt.md) and tag a site admin. diff --git a/docs/dev/documentation-guide/14-director-workflow.mdx b/docs/dev/documentation-guide/14-director-workflow.mdx new file mode 100644 index 000000000..0ff1f4eaf --- /dev/null +++ b/docs/dev/documentation-guide/14-director-workflow.mdx @@ -0,0 +1,48 @@ +--- +title: Director Workflow +--- + +import NavContainer from '@site/src/components/NavContainer'; + + + +# Director Workflow + +What the RMC Director does when reviewing a new document. The Director's role is intentionally simple: read the document, approve it, move on. The Director only reviews **new documents** (Lane 1). + +## Prerequisites + +1. A GitHub account (sign up at `github.com` if needed). +2. Membership in `@usace-rmc/docs-director` (a site admin adds you; accept the email invitation). + +One-time setup. + +## What you will be asked to do + +When a new document has passed peer review, Lead Civil review, and the technical edit, a site administrator assigns you as a reviewer. GitHub emails you. + +Click the link in the email. On the pull request page, scroll through comments to find one from a **site administrator** containing a URL starting with `https://usace-rmc.github.io/RMC-Software-Documentation/`. This is the **live production site** — the same URL readers will use. + +Click it. The document displays with a DRAFT watermark that will be removed after your approval. + +:::warning Use the live URL, not the preview URL +Use the live URL posted by the site administrator, not the automatic "Preview deployed" bot comment from earlier in the thread. The live URL is the one that matches what readers will see; the preview URL is for the earlier review stages. +::: + +Read the document. It has already been reviewed for technical accuracy (peer reviewer), technical quality (Lead Civil), and editorial quality (technical edit). Your review is a final verification that the document meets RMC standards. + +## Approving + +1. Back on the PR, click the **Files changed** tab +2. Click **Review changes** (upper right) +3. Select **Approve** +4. Optionally type a note +5. Click **Submit review** + +Done. The site administrator handles everything from here. + +## If something needs fixing + +Select **Comment** (not Approve or Request changes) and describe the issue. The author will fix it, and the site admin will ask you to re-review. + +For minor suggestions you don't want to block on, select **Approve** and include a note — the site admin will coordinate the follow-up. diff --git a/docs/dev/documentation-guide/15-site-admin-workflow.mdx b/docs/dev/documentation-guide/15-site-admin-workflow.mdx new file mode 100644 index 000000000..cf9d87dea --- /dev/null +++ b/docs/dev/documentation-guide/15-site-admin-workflow.mdx @@ -0,0 +1,138 @@ +--- +title: Site Admin Workflow +--- + +import NavContainer from '@site/src/components/NavContainer'; + + + +# Site Admin Workflow + +Responsibilities and procedures for site administrators. + +## Responsibilities + +1. Assigning reviewers (peer, Lead Civil, Director) at each stage transition +2. Running checkpoint deploys for Lane 1 PRs +3. Running or coordinating the technical edit +4. Preparing final merge commits (flipping the draft flag, updating version history) +5. Merging PRs and approving production deploys +6. Handling Lane 4 (editorial fix) and Lane 5 (dev doc) PRs as sole reviewer +7. Resolving edge cases + +## Daily routine + +Check for PRs needing your attention. The stage progression workflow tags `@usace-rmc/docs-admin` at every transition. Filter: `is:open label:"stage:ready-to-merge"` or `is:open review-requested:@me`. + +## Assigning reviewers + +Reviewers are assigned ad-hoc per PR via the Reviewers sidebar (gear icon → type username → select). There are no standing review teams for peer reviewers or Lead Civils. The workflow's transition comment tells you which role to assign next. + +For Lane 1, you assign up to three people across the lifecycle: the peer reviewer (if the author didn't), the Lead Civil after peer approval, and the Director after the technical edit. + +**Per-individual gating.** When you assign 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. You can assign multiple people at the same stage; the first approval from any of them advances the PR. + +If you assigned the wrong person or need to replace someone, remove them from the Reviewers sidebar and add the correct person. The state comment updates automatically. + +## Running a checkpoint deploy (Lane 1) + +After the author marks the technical edit complete (the PR advances to `stage:director-review`), deploy the PR branch to the live site (watermarked) for the Director's review: + +1. Repo → **Actions** tab → click **Deploy to GitHub Pages** in the sidebar +2. Click **Run workflow** dropdown (upper right) +3. Enter the PR branch name in the **ref** field +4. Click **Run workflow** +5. When the build completes, click **Review deployments** → check `production` → **Approve and deploy** +6. Verify the document on the live URL with the watermark +7. Post a comment on the PR with the live URL so the Director knows where to read + +This is the **first** time the document appears on the live site. The peer review, Lead Civil review, and technical edit all happened earlier on the preview URL or against source files; the live deploy is deferred until the document has passed editorial review. + +Re-deploy whenever the author pushes revisions during Director review. Post a comment noting the update. + +## Running the technical edit + +After the preceding review stage approves (the PR advances to `stage:ai-editor-review`), run the AI-assisted technical edit against the PR. If you don't have the necessary tooling, coordinate with a team member who does. **No deploy is required at this stage** — the technical edit reads the source MDX directly. + +The AI posts inline review comments. The author addresses them and checks the PR description checkbox to advance the PR, at which point (Lane 1) you'll run the checkpoint deploy. + +See [Technical Edit](./13-technical-edit.mdx) for the full prompt the AI uses. + +**Manual override.** If a human technical editor did the review instead, or the author isn't available to check the checkbox, apply the `admin:advance-to-director` label to the PR. The workflow removes the label and advances the stage the same as a checkbox event, then posts the next-stage instructions. + +## Preparing the final merge + +When a PR reaches `stage:ready-to-merge`: + +1. Check out the PR branch (locally or via github.dev). +2. In `src/docConfig.js`, change the document's `draft` flag from `true` to `false`. If the document is going active for the first time, also flip `active: true`. +3. Update `00-version-history.mdx` with reviewer and approver names. +4. Commit and push. +5. Merge the PR to `main`. +6. Approve the final production deploy in the Actions tab. + +For Lane 1: `reviewedBy` includes the peer reviewer and Lead Civil; `approvedBy` is the Director. +For Lane 2: `reviewedBy` is the peer reviewer and Lead Civil; `approvedBy` is `-`. +For Lane 3: `reviewedBy` is the peer reviewer; `approvedBy` is `-`. +Lanes 4 and 5: no version history update needed. + +## The `review-workflow` commit status + +Every documentation PR has a `review-workflow` commit status that branch protection on `main` requires to be `success` before the PR can merge. This is the hard merge gate — nobody, including you, can click the merge button until the bot flips this status to success. The bot manages it automatically: + +| Situation | Status | +|---|---| +| `stage:peer-review` / `stage:lead-civil-review` / `stage:ai-editor-review` / `stage:director-review` | pending | +| `stage:needs-lane` (workflow couldn't detect the lane) | pending | +| `stage:ready-to-merge` (all reviews complete) | success | +| `lane:editorial-fix` or `lane:dev` assigned | success (immediately) | +| Non-docs PR, `CI Build` passed | success | + +If a PR is stuck because `review-workflow` is pending, check the stage label to figure out what review is outstanding. If a PR is stuck because `review-workflow` is missing entirely (never got set), the lane-detection step probably failed — apply a `lane:*` label manually to re-trigger the workflow. + +## Approving deploys + +Every deploy pauses at the production environment gate. You receive an email. Navigate to Actions → the workflow run → Review deployments → check `production` → Approve and deploy. + +A Lane 1 document may involve multiple deploys: one checkpoint after the technical edit completes (for Director review), optional re-deploys during Director review if the author pushes fixes, and one final deploy after merge. + +## Handling Lane 4 and Lane 5 PRs + +Lane 4 (editorial fix) and Lane 5 (dev doc) PRs skip formal review. You are the reviewer, approver, and merger: + +1. Click the preview URL to see the change +2. Review the Files changed tab +3. Approve, merge, approve the deploy + +The `review-workflow` commit status is flipped to success immediately on lane assignment, so the merge button is enabled as soon as CI finishes. + +## Edge cases + +**Wrong lane:** Remove the current `lane:*` label, apply the correct one. The workflow re-initializes. + +**Branch starts with `docs/` but doesn't match a sub-prefix:** The workflow applies `stage:needs-lane` and tags you. Apply the correct `lane:*` label. + +**Documentation change pushed to a non-`docs/` branch:** The workflow intercepts this at PR open time regardless of branch name, because it detects changes to files under `docs/`. If the content is entirely under `docs/dev/`, it auto-assigns `lane:dev`. Otherwise it applies `stage:needs-lane` and tags you to assign the correct lane manually. Optionally ask the author to rename the branch next time for clarity. + +**Non-documentation PR with no lane comments:** Expected behavior. PRs that don't touch `docs/` are silently skipped by the lane workflow and pass the `review-workflow` status check via `CI Build`. This is normal for infrastructure, tooling, and dependency PRs. + +**Unresponsive reviewer:** Ping them on the PR, or remove them from the Reviewers sidebar and assign someone else. The state comment updates automatically. + +**Drive-by approval from an unassigned reviewer:** The workflow posts a note logging the approval but does not advance the stage. If the unassigned approver should actually be advancing the PR, add them as a reviewer via the Reviewers sidebar and ask them to re-approve — the new approval will then match the assigned list and advance the stage. + +**Author pushes new commits during an active review:** Normal and expected. The workflow does not reset the stage. The bot re-sets the `review-workflow` commit status on the new head SHA and pings the assigned reviewer(s) to backcheck. + +**Stale checkpoint deploy:** If the live URL shows outdated content, re-run the checkpoint deploy and post a comment. + +**Build fails on checkpoint deploy:** Coordinate with the author to fix the branch. + +**Build fails after merge to main:** Push a hotfix to `main` or revert the merge. Re-run the deploy. Note that `deploy.yml` filters by paths — a merge that doesn't touch any site-affecting files does not trigger a redeploy, so a broken workflow or a change to the planning folder won't break the live site. + +**Need to force a production redeploy:** Go to Actions → Deploy to GitHub Pages → Run workflow, specify the ref (usually `main`), and approve at the production gate. This is the escape hatch when the path filter would otherwise skip a merge that actually needs to ship. + +## Onboarding new site admins + +1. Clone the repo, confirm local build works. +2. Read these Documentation Guide chapters (09 through 15). +3. Shadow an existing admin through one full PR lifecycle. +4. Practice on a Lane 4 editorial fix PR. diff --git a/scripts/generateSidebars.js b/scripts/generateSidebars.js index f9c46bacd..e031e5689 100644 --- a/scripts/generateSidebars.js +++ b/scripts/generateSidebars.js @@ -370,8 +370,15 @@ function generateDocumentationGuideSidebar() { '06-creating-editing-pages', '07-react-components', '08-troubleshooting-faq', + '09-review-and-approval-overview', + '10-review-lanes', + '11-author-workflow', + '12-reviewer-workflow', + '13-technical-edit', + '14-director-workflow', + '15-site-admin-workflow', ]; - const appendixIds = ['09-appendix-a-source-code-structure', '10-appendix-b-build-process-overview', '11-appendix-c-search-configuration']; + const appendixIds = ['16-appendix-a-source-code-structure', '17-appendix-b-build-process-overview', '18-appendix-c-search-configuration']; const files = fs .readdirSync(guideDir) From dd84c6690ab4174658a05abbe5f55530ec1de488 Mon Sep 17 00:00:00 2001 From: Adam Gohs Date: Tue, 19 May 2026 10:15:52 -0400 Subject: [PATCH 4/7] Refresh README for review workflow and remove skill references - Drop the Claude Code Skills and MCP Servers sections (not everyone on the team uses Claude; skill listing belongs in .claude/skills/ only) - Add a Review and Approval Workflow section showing the five branch prefixes, their lanes, and required reviews - Note that branch protection requires CI Build and review-workflow status checks before merge - Point at Documentation Guide chapters 09-15 for full workflow details --- README.md | 54 ++++++++++++++---------------------------------------- 1 file changed, 14 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index 5a645b897..199bb8615 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ The project includes: The project is organized to support easy contribution, internal consistency, and extensibility across future RMC documentation needs. -For development standards, file structure, custom components, and styling conventions, please refer to the internal [Documentation Guide](https://usace-rmc.github.io/RMC-Software-Documentation/docs/documentation-guide/introduction/) +For development standards, file structure, custom components, and styling conventions, please refer to the internal [Documentation Guide](https://usace-rmc.github.io/RMC-Software-Documentation/docs/documentation-guide/introduction/). The guide includes: @@ -21,51 +21,25 @@ The guide includes: - Tailwind utility conventions and shared styles - Table formatting and counter file integration - Versioning strategy and linking guidelines +- The full review and approval workflow for all documentation changes -## Claude Code Skills +## Review and Approval Workflow -This repository includes Claude Code skills (slash commands) in `.claude/skills/` for common development workflows. Skills are invoked with `/{name}` in a Claude Code session. +All changes to documentation go through a pull request against the protected `main` branch. The branch prefix determines which of five review lanes the PR is routed to: -### Git & Repository +| Branch prefix | Lane | Reviews required | +|---|---|---| +| `docs/new/` | New document | Peer → Lead Civil → Technical edit → Director | +| `docs/major/` | Major revision (new major version) | Peer → Lead Civil → Technical edit | +| `docs/minor/` | Minor revision (new minor version) | Peer → Technical edit | +| `docs/fix/` | Editorial fix | None (admin self-merge) | +| `docs/dev/` | Dev docs (anything under `docs/dev/`) | None (admin self-merge) | -| Skill | Description | -|-------|-------------| -| `/commit` | Stage changes and create a git commit following project conventions | -| `/push` | Push current branch to remote with safety checks | -| `/commit-push` | Commit and push in a single operation | -| `/pr` | Create a GitHub pull request with auto-generated title and description | -| `/review-pr` | Review a pull request for code quality, MDX patterns, and documentation standards | +Each PR receives an automatic preview build at an unadvertised URL where reviewers read the rendered document. Branch protection on `main` requires both the `CI Build` and `review-workflow` status checks to pass before merge, so the merge button reflects the workflow's judgment automatically. -### Page Verification & Quality +For details on each lane, who reviews what, and step-by-step instructions for authors, reviewers, the Director, and site administrators, see chapters 9 through 15 of the [Documentation Guide](https://usace-rmc.github.io/RMC-Software-Documentation/docs/documentation-guide/introduction/). -| Skill | Description | -|-------|-------------| -| `/smoke-test` | Quick health check — page loads, no console errors, no broken images | -| `/review-responsive` | Screenshot and analyze a page at 7 device viewports (desktop through phone) | -| `/review-page` | Full page audit combining Lighthouse scores with responsive design review | -| `/check-accessibility` | Section 508 / WCAG AA compliance audit using Lighthouse + Playwright | -| `/check-performance` | Lighthouse performance audit with Core Web Vitals and resource analysis | -| `/lint-fix` | Run ESLint, auto-fix issues, and provide guidance for remaining problems | - -### Documentation & QC - -| Skill | Description | -|-------|-------------| -| `/qc-review` | Run a QC review at Level 1, 2, or 3 on an MDX document (wraps `qc/qc-prompt.md`) | -| `/build` | Run the Docusaurus production build and analyze errors/warnings | -| `/check-links` | Scan MDX files for broken references, missing images, and orphaned keys | -| `/check-components` | Validate custom component usage (props, imports, key uniqueness) in MDX files | - -### MCP Servers - -The following MCP servers enhance skill capabilities: - -- **Playwright** — Browser automation for screenshots, responsive testing, and smoke tests -- **Lighthouse** — Performance, accessibility, SEO, and best practices auditing -- **ESLint** — JavaScript linting via MCP -- **Context7** — Library documentation lookup -- **Sequential Thinking** — Multi-step reasoning for complex analysis -- **GitHub** — GitHub API integration for PR and issue workflows +## Contact For questions or support, contact the RMC documentation team: From 167a9c389d2a34a1299acfbae2cdd91aaf74ce26 Mon Sep 17 00:00:00 2001 From: Adam Gohs Date: Tue, 19 May 2026 11:46:47 -0400 Subject: [PATCH 5/7] Update Creating New Documents walkthrough for review workflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The chapter is now structured around the eight steps an author takes to publish a brand-new document via Lane 1: 1. Create a branch (new) 2. Determine folder location 3. Create folder structure 4. Add supporting assets 5. Create MDX files 6. Register the document in src/docConfig.js (new) 7. Test locally 8. Open a pull request (replaces the old 'Contact Site Administrator' step — the PR is now the coordination point and the workflow handles the deploy) The two surviving examples are trimmed to the new workflow. Example 3 (new version of existing document) was removed because new versions go through Lane 2 or Lane 3 in docs/dev/documentation-guide/02-versioning-system.mdx, not this chapter. --- .../04-creating-new-document-walkthrough.mdx | 571 +++++++----------- 1 file changed, 227 insertions(+), 344 deletions(-) diff --git a/docs/dev/documentation-guide/04-creating-new-document-walkthrough.mdx b/docs/dev/documentation-guide/04-creating-new-document-walkthrough.mdx index 9b08be074..aaf5c8890 100644 --- a/docs/dev/documentation-guide/04-creating-new-document-walkthrough.mdx +++ b/docs/dev/documentation-guide/04-creating-new-document-walkthrough.mdx @@ -32,8 +32,8 @@ Click a step to jump to the detailed section. { title: ( - Step 1: Determine Folder Location - + Step 1: Create a Branch + Go to Step 1 @@ -42,8 +42,8 @@ Click a step to jump to the detailed section. { title: ( - Step 2: Create Folder Structure - + Step 2: Determine Folder Location + Go to Step 2 @@ -52,8 +52,8 @@ Click a step to jump to the detailed section. { title: ( - Step 3: Add Supporting Assets - + Step 3: Create Folder Structure + Go to Step 3 @@ -62,8 +62,8 @@ Click a step to jump to the detailed section. { title: ( - Step 4: Create MDX Files - + Step 4: Add Supporting Assets + Go to Step 4 @@ -72,8 +72,8 @@ Click a step to jump to the detailed section. { title: ( - Step 5: Test Your Documentation - + Step 5: Create MDX Files + Go to Step 5 @@ -82,13 +82,33 @@ Click a step to jump to the detailed section. { title: ( - Step 6: Contact Site Administrator - + Step 6: Register the Document + Go to Step 6 ), }, + { + title: ( + + Step 7: Test Locally + + Go to Step 7 + + + ), + }, + { + title: ( + + Step 8: Open a Pull Request + + Go to Step 8 + + + ), + }, ]} /> @@ -101,18 +121,21 @@ This walkthrough applies to **all new document creation**, whether you're using :::info **Important** Even when using the DOCX converter (Chapter 05), you'll still need to follow most of these steps. The converter automates MDX file creation from Word documents, but you're still responsible for: -- Creating all folder structures +- Creating the branch and folder structures - Adding bibliography files - Adding source documents for archiving - Handling videos/GIFs manually (converter doesn't extract these) -- Coordinating with site administrators +- Registering the document and opening the pull request ::: **When to use this guide:** -- Creating documentation for new software -- Adding a new document type for existing software (e.g., adding validation-studies to software that only has users-guide) -- Creating a new version of existing documentation (v1.1, v2.0, etc.) +- Creating documentation for new software (Lane 1 — `docs/new/` branch) +- Adding a new document type for existing software (Lane 1 — `docs/new/` branch) + +For creating a **new version** of an existing document (v1.1, v2.0, etc.), see [Versioning System](./02-versioning-system.mdx) instead — that's Lane 2 (major revision) or Lane 3 (minor revision), not Lane 1. + +**The big picture.** Every new document goes through Lane 1 of the review workflow: you author it on a `docs/new/` branch, open a pull request, and the document is reviewed by a peer, the RMC Lead Civil, and an AI-assisted technical edit before the RMC Director gives final approval. The site administrator handles all deploys. See [Review Lanes](./10-review-lanes.mdx) and [Author Workflow](./11-author-workflow.mdx) for the full picture. --- @@ -124,7 +147,8 @@ Before you begin, gather and prepare the following: ✓ Software name and type ✓ Document type (users-guide, validation-studies, applications-guide, etc.) -✓ Version number (v1.0, v1.1, v2.0, etc.) +✓ Version number (always `v1.0` for a brand-new document) +✓ Branch slug (e.g., `docs/new/dam-analyzer-users-guide`) **Source Materials:** @@ -150,9 +174,49 @@ Before you begin, gather and prepare the following: --- -## Step 1: Determine Folder Location +## Step 1: Create a Branch + +The `main` branch is protected — you cannot push directly to it. All new documents are authored on a feature branch that gets merged via a pull request. For a new document, the branch prefix is **`docs/new/`** — this routes the PR to Lane 1 (the full review workflow with peer, Lead Civil, technical edit, and Director stages). + +**Branch naming:** `docs/new/` where the slug describes the document. Use lowercase with hyphens. + +**Examples:** + +- `docs/new/dam-analyzer-users-guide` +- `docs/new/totalrisk-applications-guide` +- `docs/new/lifesim-validation-oroville` + +### Using Git (command line) + +```bash +# Make sure your local main is up to date +git checkout main +git pull origin main + +# Create and switch to the new branch +git checkout -b docs/new/dam-analyzer-users-guide +``` + +### Using GitHub Desktop + +1. Open **GitHub Desktop** and select the `RMC-Software-Documentation` repository. +2. Click the **Current Branch** dropdown. +3. Click **New Branch**. +4. Name the branch `docs/new/`. +5. Confirm the branch is being created from `main`. +6. Click **Create Branch**. + +GitHub Desktop will switch to the new branch automatically. + +:::tip Branch name tip +Keep the slug short but specific. The branch name shows up in PR titles, commit history, and search — `dam-analyzer-users-guide` is more useful later than `new-doc` or `dam-stuff`. +::: + +--- + +## Step 2: Determine Folder Location -Before creating any folders, you need to determine exactly where your documentation belongs in the project structure. +With the branch created, you need to determine exactly where your documentation belongs in the project structure. ### Decision Process @@ -219,7 +283,7 @@ Path: docs/toolbox-technical-manuals/seismic-hazard-suite/peak-ground-accelerati --- -## Step 2: Create Folder Structure +## Step 3: Create Folder Structure You need to create folders in **five different locations** that all mirror each other. @@ -286,7 +350,7 @@ You can create folders using your file explorer, IDE, or command line. All paren --- -## Step 3: Add Supporting Assets +## Step 4: Add Supporting Assets This step can happen at different times depending on your workflow: @@ -298,7 +362,7 @@ Choose the timing that works best for you. ### Add Figures and Images -**Copy images to the figures folder** you created in Step 2. +**Copy images to the figures folder** you created in Step 3. **Figure Naming Standards:** @@ -328,7 +392,7 @@ See [Chapter 03: Project Structure - Figure Naming Standards](./03-project-struc ### Add Videos and GIFs -**Copy video files to the videos folder** you created in Step 2. +**Copy video files to the videos folder** you created in Step 3. - Supported formats: `.mp4`, `.webm`, `.gif` - Name videos descriptively: `workflow-demonstration.mp4`, `menu-navigation.gif` @@ -336,7 +400,7 @@ See [Chapter 03: Project Structure - Figure Naming Standards](./03-project-struc ### Create Bibliography File -**Create `bib.json` in the bibliographies folder** you created in Step 2. +**Create `bib.json` in the bibliographies folder** you created in Step 3. :::tip Do This Early @@ -382,7 +446,7 @@ See [Chapter 03: Project Structure - Creating bib.json with AI](./03-project-str ### Add Source Documents -**Copy source files to the source-documents folder** you created in Step 2. +**Copy source files to the source-documents folder** you created in Step 3. - Original Word documents (`.docx`) - PDFs @@ -397,7 +461,7 @@ This step is optional but highly recommended for: --- -## Step 4: Create MDX Files +## Step 5: Create MDX Files Now you're ready to create the actual documentation content. @@ -551,9 +615,47 @@ Verify the following before proceeding: --- -## Step 5: Test Your Documentation +## Step 6: Register the Document + +Every published document is registered in [`src/docConfig.js`](https://github.com/USACE-RMC/RMC-Software-Documentation/blob/main/src/docConfig.js). This file is the single source of truth for which documents appear on the site and which carry the DRAFT watermark. Without an entry, your document won't appear on the appropriate landing page, won't be indexed by search, and won't be included in the production build. + +Add a new entry to the `docs` array, grouped by category and software. For a brand-new document, start with `active: false, draft: true` — this hides the document from the production site until it's ready, but keeps it building in dev mode so you can preview it locally. The site administrator will flip these flags as part of the final merge after Director approval. + +**Example entry for a new desktop application document:** + +```javascript +{ + category: 'desktop-applications', + software: 'dam-analyzer', + doc_location: 'desktop-applications/dam-analyzer/users-guide', + doc_name: 'Dam Analyzer Users Guide', + active: false, + draft: true, +}, +``` + +**Field reference:** + +| Field | Description | +|---|---| +| `category` | One of `desktop-applications`, `toolboxes`, or `web-applications` | +| `software` | The software identifier (lowercase, hyphenated) | +| `doc_location` | Path from `docs/` to the document folder (no version, no leading slash) | +| `doc_name` | Display name shown on the landing-page tile | +| `active` | `true` to publish; `false` while drafting | +| `draft` | `true` to apply the DRAFT watermark on the latest version; `false` once finalized | + +See the existing entries in `src/docConfig.js` for examples across all categories. + +:::tip Download-only documents +If your "document" is actually a direct PDF download rather than an MDX-built site, use a `downloadUrl` field instead of `doc_location`. See the LifeSim Technical Reference Manual entry in `src/docConfig.js` as an example. +::: + +--- + +## Step 7: Test Locally -Before contacting administrators or finalizing your work, test everything locally. +Before opening the pull request, test everything locally. ### Local Testing Steps @@ -630,105 +732,61 @@ This will: --- -## Step 6: Contact Site Administrator - -Once your documentation is created and tested locally, coordinate with a site administrator for deployment and any special requirements. - -### When to Contact Administrators - -You should contact a site administrator in these situations: - -#### 1. New Software Product Requiring Navigation Links - -**When:** You're adding a completely new software product (not just a new document for existing software) - -**Why:** Administrator needs to add links to homepage or main navigation menus - -**Provide:** - -- Software name -- Application type (desktop/web/toolbox) -- Preferred display name for navigation -- Brief description of the software - -#### 2. Custom Sidebar Configuration Requirements - -**When:** Your document requires exceptions to standard rules (like non-Preface first chapter) - -**Why:** Custom sidebar configuration needs to be created manually - -**Important:** Contact administrator **BEFORE** creating your document if you know you need exceptions - -**Provide:** - -- Specific requirements (what needs to be different) -- Clear justification for the exception -- Proposed alternative approach +## Step 8: Open a Pull Request -#### 3. Deployment Coordination +When local testing passes, commit your work and open a pull request. The `docs/new/` branch prefix routes the PR to **Lane 1** of the review workflow: peer review → RMC Lead Civil review → AI technical edit → Director approval. -**When:** Always - for every new document +### Commit and push -**Why:** Administrator handles deployment, coordinates timing, marks drafts - -**Provide:** +```bash +# Stage everything you've added +git add docs/ static/ src/docConfig.js -- Target deployment date -- Any timing constraints or dependencies -- Whether document should initially be marked as DRAFT -- Software release dependencies (if applicable) +# Commit with a descriptive message +git commit -m "Add Dam Analyzer Users Guide v1.0" -#### 4. New Component or Feature Requests +# Push the branch to GitHub +git push -u origin docs/new/dam-analyzer-users-guide +``` -**When:** Standard components don't meet your documentation needs +GitHub Desktop users: stage and commit via the **Changes** panel, then click **Publish branch**. -**Why:** Custom React components require development by administrators +### Open the pull request -**Provide:** +After pushing, GitHub returns a URL like `https://github.com/USACE-RMC/RMC-Software-Documentation/pull/new/`. Click it to open the PR creation page (or use the **Pull Requests** tab on GitHub). -- Description of needed functionality -- Examples of what you're trying to accomplish -- Visual mockups or references (if available) +The repository ships a PR template that prefills a description structure. Fill in the sections: -### What to Include in Your Message +- **Description** — what document you're adding and why +- **Affected documents** — the path you created +- **Related issues** — any tracked issues this addresses +- **Pre-submission checklist** — confirm branch prefix, local preview, and version-history entry +- **Technical edit checkbox** — leave unchecked until later in the review -Use this template when contacting administrators: +Click **Create pull request**. -``` -Subject: New Documentation: [Software Name] [Document Type] +### What happens automatically -Hello, +Within a minute or two of opening the PR: -I've created new documentation and need administrator assistance: +1. A **preview build** is published to an unadvertised URL. Look for the bot comment that says "Preview deployed." +2. The stage progression workflow assigns `lane:new-doc` and `stage:peer-review` labels, and posts a comment identifying the lane and what's needed next. +3. The `review-workflow` merge gate is set to `pending` — `main` cannot be merged into until the workflow flips it to success. -**Document Details:** -- Software: [software name] -- Document Type: [users-guide, validation-studies, etc.] -- Location: docs/[full-path-to-document]/ -- Version: v1.0 +### What you do next -**Administrator Tasks Needed:** -☐ Homepage/navigation links for new software -☐ Custom sidebar configuration (explain why) -☐ Deployment coordination (specify timing) -☐ Mark as DRAFT initially (if applicable) -☐ New component request (describe need) +If you have a peer reviewer in mind, assign them via the **Reviewers** sidebar. If you don't, the site administrator will assign one. From here on, follow the [Author Workflow](./11-author-workflow.mdx) chapter — it covers responding to reviewer comments, addressing the technical edit, and what to expect through each review stage. -**Deployment Timing:** -[Target date or "Ready when convenient" or specific constraints] +### When something special is needed -**Additional Context:** -[Any relevant details, deadlines, special considerations, or questions] +The PR comment thread is the place to coordinate anything unusual. Tag `@usace-rmc/docs-admin` in a comment if: -**Testing Status:** -- Local testing completed successfully -- All figures display correctly -- No console errors -- Ready for QA review +- This is a completely new software product that needs homepage or navigation links added +- The document needs an exception from the standard sidebar structure (e.g., the first chapter isn't a "Preface") +- You need a new React component that doesn't exist yet +- The document has a specific deployment-timing dependency (e.g., must go live alongside a software release) -Thank you! -[Your name] -``` +You no longer need to email the administrator with a deployment request — the PR itself is the coordination point, and the workflow handles the deploy automatically once the review is complete. --- @@ -736,271 +794,95 @@ Thank you! ### Example 1: New Desktop Application Users Guide -**Scenario:** Creating users guide for new desktop application called "Dam Safety Tool" version 1.0 - -**Step-by-Step:** +**Scenario:** Creating a Users Guide for a new desktop application called "Dam Safety Tool," version 1.0. -**1. Determine Location** +**1. Create a branch:** `docs/new/dam-safety-tool-users-guide` off `main`. +**2. Determine location:** - Application type: Desktop → `desktop-applications/` -- Software name: `dam-safety-tool` -- Document type: `users-guide` -- Version: `v1.0` -- **Full path:** `docs/desktop-applications/dam-safety-tool/users-guide/v1.0/` +- Full path: `docs/desktop-applications/dam-safety-tool/users-guide/v1.0/` -**2. Create Folders** +**3. Create folders** (docs, figures, videos, bibliographies, source-documents — all mirroring the same path). -```bash -docs/desktop-applications/dam-safety-tool/users-guide/v1.0/ -static/figures/desktop-applications/dam-safety-tool/users-guide/v1.0/ -static/videos/desktop-applications/dam-safety-tool/users-guide/v1.0/ -static/bibliographies/desktop-applications/dam-safety-tool/users-guide/v1.0/ -static/source-documents/desktop-applications/dam-safety-tool/users-guide/v1.0/ -``` +**4. Add assets:** 45 screenshots, 3 demo videos, a `bib.json` with 12 references, and the source Word document. -**3. Add Assets** +**5. Create MDX** using the DOCX converter (Chapter 05) → 8 chapter files generated automatically. -- Copy 45 PNG screenshots to figures folder -- Copy 3 demo videos (MP4) to videos folder -- Create bib.json with 12 references using AI assistance -- Copy original Word document to source-documents folder - -**4. Create MDX** (Using DOCX converter) - -- Run converter on source Word document -- Converter creates 8 chapter files automatically -- Review and verify all files - -**5. Test Locally** - -- Run `npm start` -- Navigate to document in browser -- Verify all 45 figures display -- Test video playback -- Check citations render correctly -- No console errors - -**6. Contact Administrator** +**6. Register in `src/docConfig.js`:** +```javascript +{ + category: 'desktop-applications', + software: 'dam-safety-tool', + doc_location: 'desktop-applications/dam-safety-tool/users-guide', + doc_name: 'Dam Safety Tool Users Guide', + active: false, + draft: true, +}, ``` -Subject: New Documentation: Dam Safety Tool Users Guide - -Hello, - -I've created new documentation for a new desktop application. -**Document Details:** -- Software: Dam Safety Tool -- Document Type: users-guide -- Location: docs/desktop-applications/dam-safety-tool/users-guide/v1.0/ -- Version: v1.0 +**7. Test locally** with `npm start`. Verify all figures display, videos play, citations render, and there are no console errors. -**Administrator Tasks Needed:** -☑ Homepage/navigation links for new software -☐ Custom sidebar configuration -☑ Deployment coordination - ready ASAP -☑ Mark as DRAFT initially until software is released -☐ New component request - -**Deployment Timing:** -Software releases March 2026, but documentation can go live as DRAFT now -for internal review. - -**Testing Status:** -- Local testing completed successfully -- All 45 figures display correctly -- 3 videos play correctly -- No console errors -- Ready for QA review - -Thank you! -``` +**8. Open the pull request:** push the branch, open the PR, fill in the template, and let the workflow take over. Because this is a brand-new software product, add a comment tagging `@usace-rmc/docs-admin` to request the homepage/navigation links be added — that's an admin task that runs alongside the review. ### Example 2: New Toolbox Technical Manual -**Scenario:** Adding new tool "Seepage Analysis" to existing seismic-hazard-suite +**Scenario:** Adding a new tool "Seepage Analysis" to the existing seismic-hazard-suite. -**Step-by-Step:** - -**1. Determine Location** +**1. Create a branch:** `docs/new/seepage-analysis-toolbox` off `main`. +**2. Determine location:** - Application type: Toolbox → `toolbox-technical-manuals/` -- Suite name: `seismic-hazard-suite` (existing) -- Tool name: `seepage-analysis` (new) -- Version: `v1.0` -- **Full path:** `docs/toolbox-technical-manuals/seismic-hazard-suite/seepage-analysis/v1.0/` - -**2. Create Folders** +- Full path: `docs/toolbox-technical-manuals/seismic-hazard-suite/seepage-analysis/v1.0/` -```bash -docs/toolbox-technical-manuals/seismic-hazard-suite/seepage-analysis/v1.0/ -static/figures/toolbox-technical-manuals/seismic-hazard-suite/seepage-analysis/v1.0/ -static/bibliographies/toolbox-technical-manuals/seismic-hazard-suite/seepage-analysis/v1.0/ -static/source-documents/toolbox-technical-manuals/seismic-hazard-suite/seepage-analysis/v1.0/ -``` +**3. Create folders** (docs, figures, bibliographies, source-documents — no videos needed for this document). -(No videos folder - not needed for this document) +**4. Add assets:** 15 diagrams, a `bib.json` with 8 references, and the Excel tool as the source document. -**3. Add Assets** +**5. Create MDX manually** (no source Word document): +- `00-document-info.mdx` with `` +- `00-version-history.mdx` with the initial v1.0 entry +- `01-preface.mdx` +- Four more chapters (`02-` through `05-`) -- Copy 15 PNG diagrams to figures folder -- Create bib.json with 8 references -- Copy Excel tool to source-documents folder - -**4. Create MDX** (Manual creation - no Word document) - -- Create 00-document-info.mdx with DocumentMetadata -- Create 00-version-history.mdx with initial v1.0 entry -- Create 01-preface.mdx -- Create 4 more chapter files (02-05) -- Reference figures and citations throughout - -**5. Test Locally** - -- Run `npm start` -- Navigate to seismic-hazard-suite in sidebar -- Verify new tool appears under the suite -- Test all chapters load -- Verify figure numbering -- No console errors - -**6. Contact Administrator** +**6. Register in `src/docConfig.js`:** +```javascript +{ + category: 'toolboxes', + software: 'seismic-hazard-suite', + doc_location: 'toolbox-technical-manuals/seismic-hazard-suite/seepage-analysis', + doc_name: 'Seepage Analysis Toolbox Technical Manual', + active: false, + draft: true, +}, ``` -Subject: New Documentation: Seepage Analysis Technical Manual - -Hello, - -I've added a new tool to the existing seismic-hazard-suite. -**Document Details:** -- Suite: seismic-hazard-suite (existing) -- Tool: seepage-analysis (new) -- Document Type: technical manual -- Location: docs/toolbox-technical-manuals/seismic-hazard-suite/seepage-analysis/v1.0/ -- Version: v1.0 +**7. Test locally** — verify the new tool appears under the existing seismic-hazard-suite in the sidebar. -**Administrator Tasks Needed:** -☐ Homepage/navigation links (not needed - suite already exists) -☐ Custom sidebar configuration -☑ Deployment coordination - ready when convenient -☐ Mark as DRAFT -☐ New component request - -**Deployment Timing:** -Ready for deployment anytime. No dependencies. - -**Testing Status:** -- Local testing completed successfully -- All 15 figures display correctly -- No console errors -- Ready for deployment - -Thank you! -``` - -### Example 3: New Version of Existing Document - -**Scenario:** Creating v1.1 of LifeSim Users Guide (updating existing v1.0) - -**Step-by-Step:** - -**1. Determine Location** - -- Use existing path structure: `docs/desktop-applications/lifesim/users-guide/` -- Add new version folder: `v1.1` -- **Full path:** `docs/desktop-applications/lifesim/users-guide/v1.1/` - -**2. Copy from Previous Version** - -```bash -# Copy entire v1.0 folder to v1.1 -cp -r docs/desktop-applications/lifesim/users-guide/v1.0/ docs/desktop-applications/lifesim/users-guide/v1.1/ - -# Copy figures -cp -r static/figures/desktop-applications/lifesim/users-guide/v1.0/ static/figures/desktop-applications/lifesim/users-guide/v1.1/ - -# Copy bibliographies -cp -r static/bibliographies/desktop-applications/lifesim/users-guide/v1.0/ static/bibliographies/desktop-applications/lifesim/users-guide/v1.1/ - -# Copy videos if they exist -cp -r static/videos/desktop-applications/lifesim/users-guide/v1.0/ static/videos/desktop-applications/lifesim/users-guide/v1.1/ -``` - -**3. Update Version-Specific Content** - -- Edit `00-document-info.mdx` - change version to "1.1" -- Edit `00-version-history.mdx` - add new entry for v1.1 with changes -- Update any version-specific screenshots or references -- Make content changes for the new version - -**4. Test Locally** - -- Run `npm start` -- Navigate to LifeSim in sidebar -- Verify both v1.0 and v1.1 appear in version selector -- Switch between versions to ensure both work -- Test new/modified content in v1.1 - -**5. Contact Administrator** - -``` -Subject: New Version: LifeSim Users Guide v1.1 - -Hello, - -I've created v1.1 of the LifeSim Users Guide. - -**Document Details:** -- Software: LifeSim (existing) -- Document Type: users-guide (existing) -- Location: docs/desktop-applications/lifesim/users-guide/v1.1/ -- Version: v1.1 (new version of existing document) - -**Administrator Tasks Needed:** -☐ Homepage/navigation links (already exists) -☐ Custom sidebar configuration -☑ Deployment coordination - coordinate with software release -☐ Mark as DRAFT -☐ New component request - -**Deployment Timing:** -LifeSim v1.1 software releases February 15, 2026. -Documentation should go live the same day. - -**Changes in v1.1:** -- Updated Chapter 4 with new analysis features -- Added 5 new screenshots for new features -- Updated bibliography with 2 new references -- Minor corrections throughout - -**Testing Status:** -- Local testing completed successfully -- Version selector works correctly between v1.0 and v1.1 -- All new figures display correctly -- No console errors -- Ready for deployment - -Thank you! -``` +**8. Open the pull request.** Because the suite already exists, no admin coordination is needed for navigation — the workflow handles everything once the review is complete. --- ## Quick Reference Checklist -Use this scannable checklist to ensure you've completed all steps: +Use this scannable checklist to confirm every step is complete: ### Pre-Creation ✓ Source materials gathered ✓ Folder location determined ✓ Document type selected -✓ Version number decided +✓ Branch slug decided (e.g., `docs/new/dam-analyzer-users-guide`) ✓ Creation method chosen (DOCX converter vs. manual) +### Branch + +✓ Created branch with `docs/new/` prefix off `main` + ### Folder Structure -✓ Created docs folder: `docs/[application-type]/[software]/[document-type]/[version]/` +✓ Created docs folder: `docs/[application-type]/[software]/[document-type]/v1.0/` ✓ Created figures folder: `static/figures/[matching-path]/` ✓ Created videos folder (if needed): `static/videos/[matching-path]/` ✓ Created bibliographies folder: `static/bibliographies/[matching-path]/` @@ -1023,6 +905,11 @@ Use this scannable checklist to ensure you've completed all steps: ✓ All file names use lowercase with hyphens ✓ Front matter complete in all files +### Registration + +✓ Added an entry to `src/docConfig.js` for the new document +✓ Set `active: false, draft: true` for initial state + ### Testing ✓ Ran `npm start` without errors @@ -1035,18 +922,14 @@ Use this scannable checklist to ensure you've completed all steps: ✓ No console errors in browser developer tools ✓ Internal links work -### Finalization - -✓ Contacted administrator with deployment details -✓ Specified administrator tasks needed: +### Pull Request -- Navigation links (if new software) -- Custom sidebar (if exceptions needed) -- Deployment coordination and timing -- DRAFT marking (if not ready for public) -- Component requests (if needed) -- Committed changes to repository (after admin approval) -- Documented any special configurations +✓ Pushed branch to remote +✓ Opened PR via GitHub web interface or IDE +✓ Filled in PR template description +✓ Verified `lane:new-doc` and `stage:peer-review` labels were applied automatically +✓ Verified preview URL builds and displays the new document +✓ Tagged `@usace-rmc/docs-admin` with any special requests (new-software navigation links, custom sidebar exception, new component request, deployment-timing dependency) --- From b3e66b3e26a9a8937bc85df412caea897a5b302d Mon Sep 17 00:00:00 2001 From: Adam Gohs Date: Tue, 19 May 2026 11:46:58 -0400 Subject: [PATCH 6/7] Rewrite review-process chapters in third person with shared components - Convert every 'you' to third-person voice describing role behavior (e.g., 'The author addresses each comment' rather than 'You address each comment'). The chapters now read as reference material for any team member, not as instructions addressed to the role-holder. - Replace markdown tables with TableVerticalNoRef so styling matches the rest of the site (zebra striping, alt text, responsive scroller). - Replace ordered/numbered procedure lists with ProcessList components so visual treatment matches existing chapters. --- .../09-review-and-approval-overview.mdx | 131 +++++++--- .../documentation-guide/10-review-lanes.mdx | 58 +++-- .../11-author-workflow.mdx | 120 +++++---- .../12-reviewer-workflow.mdx | 84 ++++-- .../documentation-guide/13-technical-edit.mdx | 100 +++++--- .../14-director-workflow.mdx | 43 ++-- .../15-site-admin-workflow.mdx | 241 ++++++++++++------ 7 files changed, 503 insertions(+), 274 deletions(-) diff --git a/docs/dev/documentation-guide/09-review-and-approval-overview.mdx b/docs/dev/documentation-guide/09-review-and-approval-overview.mdx index f936b2595..9376cadcb 100644 --- a/docs/dev/documentation-guide/09-review-and-approval-overview.mdx +++ b/docs/dev/documentation-guide/09-review-and-approval-overview.mdx @@ -3,56 +3,105 @@ title: Review and Approval Process Overview --- import NavContainer from '@site/src/components/NavContainer'; +import TableVerticalNoRef from '@site/src/components/TableVerticalNoRef'; # 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 jump to the role-specific chapter that applies to you. - -## Who participates - -**Author.** Writes or revises the document. The only role that needs local development tooling — everyone else works in a web browser. - -**Peer reviewer.** Subject-matter expert assigned ad-hoc to review technical accuracy. Works entirely in the GitHub web interface, reading the document on an unadvertised preview URL. - -**RMC Lead Civil.** Provides technical oversight and quality assurance. Assigned ad-hoc per document. Works in the GitHub web interface, also reviewing on the preview URL. - -**Technical edit (AI-assisted).** An AI-powered editorial review that checks grammar, clarity, tense, terminology, and Section 508 accessibility compliance. A team member with the right tooling triggers the review, and the AI posts inline comments directly on the pull request. A human technical editor can be substituted at the site admin's discretion. - -**Director.** The RMC Director provides final approval for new documents only. Reviews the document on the live site (with a DRAFT watermark) and clicks Approve — no file editing required. - -**Site administrator.** Manages reviewer assignments, checkpoint deploys, merge preparation, and final deploys. The only role with access to protected parts of the repository. +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. + + ## The five review lanes -Every change falls into one of five lanes based on its scope: - -**Lane 1: New document.** Peer review → Lead Civil review → Technical edit → Director approval. The peer review, Lead Civil review, and technical edit all happen against the preview URL or the source files. Only after the technical edit completes does the site admin deploy the document to the live site (watermarked) for Director review at the document's final URL. - -**Lane 2: Major revision.** Peer review → Lead Civil review. Entire review happens on the preview site. Site admin deploys the final version after Lead Civil approval. - -**Lane 3: Minor revision.** Peer review only on the preview site. - -**Lane 4: Editorial fix.** Site admin reviews and deploys directly. No formal review. - -**Lane 5: Dev docs.** Any change to documents under `docs/dev/` — developer documentation, contributor guides, internal references. Treated like Lane 4 — site admin reviews and merges directly, no formal review required. - -See [Review Lanes](./10-review-lanes.mdx) for branch-prefix conventions and detailed examples of each lane. +Every change falls into one of five lanes based on its scope. + + + +For Lane 1, peer review, Lead Civil review, and the technical edit all happen against the preview URL or the source MDX files. Only after the technical edit completes does the site administrator deploy the document to the live site (watermarked) for Director review at the document's final URL. For Lanes 2 and 3, the entire review happens on the preview URL — the live site continues to show the previously-published version, unwatermarked. + +See [Review Lanes](./10-review-lanes.mdx) for branch-prefix conventions and detailed examples. ## The merge gate -Every documentation PR has a GitHub commit status called `review-workflow` that functions as the merge gate. Branch protection on `main` requires this status to be `success` before the PR can merge, so nobody — not even a site admin — can merge a PR whose review is incomplete. The stage progression workflow sets this status automatically: - -- **Pending** during any active review stage (`stage:peer-review`, `stage:lead-civil-review`, `stage:ai-editor-review`, `stage:director-review`, or `stage:needs-lane`) -- **Success** when the PR reaches `stage:ready-to-merge`, or immediately on lane assignment for `lane:editorial-fix` and `lane:dev` -- **Success** for non-docs PRs (infrastructure, tooling, dependency updates) as soon as `CI Build` passes - -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 admin's discretion. +Every documentation 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. The stage progression workflow sets the status automatically. + + + +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. For Lane 1, the watermark appears on the live site during the Director review phase only — the document is not deployed to the live site until the technical edit is complete. The watermark signals to any reader who happens to find the live URL that the content is not yet authoritative. The watermark is removed when the site admin flips the draft flag after Director approval. +Documents flagged as drafts display a large diagonal "DRAFT" watermark. For Lane 1, the watermark appears on the live site during the Director review phase only — the document is not deployed to the live site until the technical edit is complete. The watermark signals to any reader who finds the live URL that the content is not yet authoritative, and it is removed when the site administrator flips the draft flag after Director approval. 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. @@ -60,8 +109,8 @@ The watermark is **version-aware**: it renders only on the latest version of a f ## Where to go next -- Authoring a document: read [Review Lanes](./10-review-lanes.mdx), then [Author Workflow](./11-author-workflow.mdx) -- Asked to review: read [Reviewer Workflow](./12-reviewer-workflow.mdx) -- Running a technical edit: read [Technical Edit](./13-technical-edit.mdx) -- Director reviewing a new document: read [Director Workflow](./14-director-workflow.mdx) -- Site administrator: read [Site Admin Workflow](./15-site-admin-workflow.mdx) +- Authoring a document: see [Review Lanes](./10-review-lanes.mdx) and [Author Workflow](./11-author-workflow.mdx) +- Reviewing as a peer or Lead Civil: see [Reviewer Workflow](./12-reviewer-workflow.mdx) +- Running a technical edit: see [Technical Edit](./13-technical-edit.mdx) +- Director approval for a new document: see [Director Workflow](./14-director-workflow.mdx) +- Site administration: see [Site Admin Workflow](./15-site-admin-workflow.mdx) diff --git a/docs/dev/documentation-guide/10-review-lanes.mdx b/docs/dev/documentation-guide/10-review-lanes.mdx index 321a0a588..127861898 100644 --- a/docs/dev/documentation-guide/10-review-lanes.mdx +++ b/docs/dev/documentation-guide/10-review-lanes.mdx @@ -3,6 +3,7 @@ title: Review Lanes --- import NavContainer from '@site/src/components/NavContainer'; +import TableVerticalNoRef from '@site/src/components/TableVerticalNoRef'; @@ -11,21 +12,34 @@ import NavContainer from '@site/src/components/NavContainer'; Every change follows one of five review lanes. The workflow assigns a lane automatically using two signals, in order: 1. **Content-based detection.** If every documentation file changed in the PR is under `docs/dev/`, the PR is assigned `lane:dev` regardless of branch name. -2. **Branch-name detection.** Otherwise, the branch prefix determines the lane: - -| Branch prefix | Lane | -|---|---| -| `docs/new/` | New document | -| `docs/major/` | Major revision | -| `docs/minor/` | Minor revision | -| `docs/fix/` | Editorial fix | -| `docs/dev/` | Dev docs | - -**Any PR that touches files under `docs/` is processed by the review workflow**, even if its branch name doesn't start with `docs/`. This means a collaborator can accidentally push a documentation change on a branch named `feature/typo-fix` and the workflow will still intercept it at PR open time and ask a site admin to assign a lane. Non-documentation PRs (branches that don't touch anything under `docs/`) are silently ignored by the lane workflow and go straight to the merge button once their build passes. - -If a branch starts with `docs/` but doesn't match one of the five sub-prefixes above (for example, a typo like `docs/newfoo/` or an old-style name like `docs/update`), the workflow applies `stage:needs-lane` and tags a site admin to assign the correct lane manually. The same happens for a PR that touches documentation from a non-`docs/` branch when content-based dev detection doesn't apply. - -A site admin can always override the automatically-detected lane by swapping the `lane:*` label on the PR. The workflow treats a manually-applied lane label the same as an auto-detected one and proceeds normally from there. +2. **Branch-name detection.** Otherwise, the branch prefix determines the lane. + + + +Any PR that touches files under `docs/` is processed by the review workflow, even if its branch name does not start with `docs/`. A documentation change accidentally pushed on a branch named `feature/typo-fix` is still intercepted at PR open time, and a site administrator is asked to assign a lane. Non-documentation PRs (branches that do not touch anything under `docs/`) are silently ignored by the lane workflow and go straight to the merge button once their build passes. + +If a branch starts with `docs/` but does not match one of the five sub-prefixes above — for example, a typo like `docs/newfoo/` or an old-style name like `docs/update` — the workflow applies `stage:needs-lane` and tags a site administrator to assign the correct lane manually. The same happens for a PR that touches documentation from a non-`docs/` branch when content-based dev detection does not apply. + +A site administrator can always override the automatically-detected lane by swapping the `lane:*` label on the PR. The workflow treats a manually-applied lane label the same as an auto-detected one and proceeds normally from there. ## Lane 1: New document @@ -33,7 +47,7 @@ A site admin can always override the automatically-detected lane by swapping the **Required reviews.** Peer review → RMC Lead Civil review → Technical edit (AI-assisted) → Director approval. -**What happens.** The document is first visible only on the unadvertised PR preview URL, where peer review, Lead Civil review, and the technical edit all happen. The technical edit reads the source MDX directly and posts inline comments — it does not need a deployed version. Only after the author marks the technical edit complete does the site admin deploy the PR branch to the live production site with the DRAFT watermark. The Director then reviews on the live URL. After Director approval, the site admin flips the draft flag, merges the PR, and deploys the final version — removing the watermark. +**What happens.** The document is first visible only on the unadvertised PR preview URL, where peer review, Lead Civil review, and the technical edit all happen. The technical edit reads the source MDX directly and posts inline comments — no deployed version is required. Only after the author marks the technical edit complete does the site administrator deploy the PR branch to the live production site with the DRAFT watermark. The Director then reviews on the live URL. After Director approval, the site administrator flips the draft flag, merges the PR, and deploys the final version — removing the watermark. **Example branches:** `docs/new/totalrisk-applications-guide`, `docs/new/lifesim-validation-oroville` @@ -43,7 +57,7 @@ A site admin can always override the automatically-detected lane by swapping the **Required reviews.** Peer review → RMC Lead Civil review → Technical edit (AI-assisted). -**What happens.** The entire review happens on the preview URL. The old version stays live and unwatermarked. After the technical edit comments are addressed, the site admin flips the draft flag, merges, and deploys. The new version becomes the default; the old version remains accessible via direct URL. +**What happens.** The entire review happens on the preview URL. The old version stays live and unwatermarked. After the technical edit comments are addressed, the site administrator flips the draft flag, merges, and deploys. The new version becomes the default; the old version remains accessible via direct URL. **Example branches:** `docs/major/bep-progression-v2.0` @@ -59,9 +73,9 @@ A site admin can always override the automatically-detected lane by swapping the ## Lane 4: Editorial fix -**When to use.** Typos, broken links, grammatical corrections that don't change technical meaning. +**When to use.** Typos, broken links, grammatical corrections that do not change technical meaning. -**Required reviews.** None. Site admin reviews and merges directly. +**Required reviews.** None. The site administrator reviews and merges directly. **No version change, no watermark.** @@ -71,9 +85,9 @@ A site admin can always override the automatically-detected lane by swapping the **When to use.** Any new or revised document under `docs/dev/` — developer documentation, contributor guides, internal references, planning documents, and similar materials. -**Required reviews.** None. Site admin reviews and merges directly, same as Lane 4. +**Required reviews.** None. The site administrator reviews and merges directly, same as Lane 4. -**Automatic assignment.** The workflow uses content-based detection: if every documentation file changed in the PR is under `docs/dev/`, the PR is assigned `lane:dev` regardless of what the branch is called. This means dev docs can be authored on any branch prefix (including non-`docs/` branches) and still end up in the correct lane. +**Automatic assignment.** The workflow uses content-based detection: if every documentation file changed in the PR is under `docs/dev/`, the PR is assigned `lane:dev` regardless of branch name. Dev docs can therefore be authored on any branch prefix (including non-`docs/` branches) and still end up in the correct lane. **No version change, no watermark.** @@ -81,4 +95,4 @@ A site admin can always override the automatically-detected lane by swapping the ## Choosing the right lane -When in doubt, choose the more conservative lane. A site admin can reassign lanes by swapping `lane:*` labels. +When in doubt, the author should choose the more conservative lane. A site administrator can reassign lanes by swapping `lane:*` labels. diff --git a/docs/dev/documentation-guide/11-author-workflow.mdx b/docs/dev/documentation-guide/11-author-workflow.mdx index f4acfb8df..3a0ad3537 100644 --- a/docs/dev/documentation-guide/11-author-workflow.mdx +++ b/docs/dev/documentation-guide/11-author-workflow.mdx @@ -3,86 +3,114 @@ title: Author Workflow --- import NavContainer from '@site/src/components/NavContainer'; +import ProcessList from '@site/src/components/ProcessList'; +import TableVerticalNoRef from '@site/src/components/TableVerticalNoRef'; # Author Workflow -What the author does from start to publication, across all five lanes. +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](./10-review-lanes.mdx) for the mapping. -**For a new document (Lane 1):** - -1. Create a `docs/new/` branch off `main`. -2. Create the directory structure under `docs/` with a `v1.0/` folder. -3. Add boilerplate MDX files following the [Project Structure](./03-project-structure.mdx) conventions. -4. Register the new document in `src/docConfig.js` with `active: false, draft: true` so it's hidden from the prod build and watermarked once activated. - -**For a revision (Lanes 2 and 3):** - -1. Create a `docs/major/-` or `docs/minor/-` branch off `main`. -2. Copy the current version folder to the new version (e.g., `cp -r v1.0/ v1.1/`). -3. Mirror the version folder for figures, bibliography, and source documents under `static/figures/`, `static/bibliographies/`, and `static/source-documents/`. -4. Flip `draft: true` on the document's entry in `src/docConfig.js`. -5. Add a placeholder row to `00-version-history.mdx`. - -**For an editorial fix (Lane 4):** - -1. Create a `docs/fix/` branch off `main`. -2. Edit the file directly. No version change. - -**For a dev doc (Lane 5):** - -1. Create a branch (`docs/dev/` prefix recommended but not required — content-based detection routes any PR whose files are all under `docs/dev/` to Lane 5). -2. Edit files under `docs/dev/`. - -All steps can be done 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). +', + 'docs/major/-v', + 'docs/minor/-v', + 'docs/fix/', + 'docs/dev/ (or any branch — content-based detection routes any PR whose docs files are all under docs/dev/ to Lane 5)', + ], + [ + 'Scaffold the document directory and v1.0/ folder, register the document in src/docConfig.js with active: false, draft: true', + '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', + 'Same as Lane 2 but for a minor version bump (e.g., v1.1/)', + 'Edit the file directly. No version change required.', + '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 -Open a PR via the GitHub web interface or your IDE's PR integration. The repository ships a PR template that prefills a description structure — fill in the sections (Description, Affected documents, Related issues, Pre-submission checklist, and the Technical edit checkbox for Lane 1). Assign your peer reviewer in the Reviewers sidebar if you know who it should be; otherwise the site admin will assign one. +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: -Within minutes, two bot comments appear on the PR: a preview URL and a stage progression comment identifying your lane. A third hidden bot comment tracks which individuals the site admin has assigned to each review stage — it renders as an "Assigned reviewers for this PR" block at the top of the PR comment thread. +1. A preview URL where reviewers will read the rendered document +2. A stage progression comment identifying the lane and what review is needed next +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 ## Responding to review comments -Reviewers post comments on specific lines in the Files changed tab. For each comment: make the fix, push a commit, reply explaining what you did. The reviewer resolves the thread when satisfied. +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), you can click "Commit suggestion" to apply the fix in one click. +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 on the PR 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. +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. -Address each comment the same way you address human reviewer comments — push fixes, reply, and either you or the site admin can resolve threads as they're addressed. +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 you've addressed all technical edit comments,** check the checkbox in the PR description: +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` +``` +- [x] Technical edit comments addressed — ready for Director review +``` -Checking this box is what advances the document to the next stage (Director review for Lane 1, ready-to-merge for Lanes 2 and 3). Don't check it until you've addressed all comments. +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](./13-technical-edit.mdx) for the full prompt the AI uses and the alternative human-editor path. -## Where reviewers read your document - -**Lane 1.** Peer review and Lead Civil review happen on the **preview URL**. The technical edit reads the source MDX directly and posts inline comments on the PR — no deploy is involved. Only after you mark the technical edit complete does the site admin deploy the document to the **live production site** (watermarked) for **Director review**. If you push revisions during Director review, the site admin re-deploys so the live URL stays current. - -**Lanes 2 and 3.** All review happens on the preview URL only. - -**Lanes 4 and 5.** The site admin reviews on the preview URL (if generated) or directly in the Files changed tab, then merges. +## Where reviewers read the document + + + +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 their feedback as a **Comment** review (not "Request changes"), leaving inline notes on specific lines. Address each comment, push a new commit, and reply to the thread explaining what you did. You don't need to do anything else — the stage progression bot automatically pings the assigned reviewer(s) on your PR to come back and backcheck. +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 you push new commits.** A revision during peer review is for the peer reviewer to backcheck; it does not send the document back to start. Same for Lead Civil review and Director review. This is intentional — you're building on the review that already happened, not starting over. +**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 admin prepares the merge: flips the draft flag in `src/docConfig.js`, updates the version history, merges the PR, and approves the final deploy. You'll see email notifications as this happens. Once the deploy completes, your document is live. +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. diff --git a/docs/dev/documentation-guide/12-reviewer-workflow.mdx b/docs/dev/documentation-guide/12-reviewer-workflow.mdx index 315b9c0b6..2b624567e 100644 --- a/docs/dev/documentation-guide/12-reviewer-workflow.mdx +++ b/docs/dev/documentation-guide/12-reviewer-workflow.mdx @@ -3,59 +3,87 @@ title: Reviewer Workflow --- import NavContainer from '@site/src/components/NavContainer'; +import ProcessList from '@site/src/components/ProcessList'; +import TableVerticalNoRef from '@site/src/components/TableVerticalNoRef'; # Reviewer Workflow -What peer reviewers and RMC Lead Civils do when assigned to review a documentation pull request. Written for someone with little GitHub experience. Everything can be done from a web browser. +What peer reviewers and RMC Lead Civils do when assigned to review a documentation pull request. Everything in this workflow happens through the GitHub web interface — no local tooling is required. ## Prerequisites -You need a GitHub account and membership in the `usace-rmc` organization. A site administrator will send you an invitation — click the link in the email to accept. +A reviewer needs a GitHub account and membership in the `usace-rmc` organization. A site administrator sends the invitation by email; the reviewer clicks the link to accept. ## Receiving a review request -GitHub emails you with subject "You were requested to review [title]." Click the link to open the PR. +GitHub emails the reviewer with the subject "You were requested to review [title]." The link in the email opens the PR. ## Where to read the document -**Both peer reviewers and Lead Civils review on the preview URL.** In the PR's comment thread, look for a bot comment that says "Preview deployed" with a URL. Click it. This opens the rendered document on an unadvertised preview site with a DRAFT watermark. - -Read the document as you would any web page. This is where your review happens — you are reading, not editing. - -**Peer reviewers:** Focus on technical accuracy. Are claims correct? Equations right? Procedures complete? - -**Lead Civils:** Focus on technical quality and oversight. Does the document meet RMC standards? Is the scope appropriate? Are conclusions defensible? +Both peer reviewers and Lead Civils review on the preview URL. The PR's comment thread contains a bot comment titled "Preview deployed" with a URL. The link opens the rendered document on an unadvertised preview site with a DRAFT watermark. + +The reviewer reads the document as they would any web page. The review happens in the rendered preview — reviewers do not edit files. + + ## Leaving feedback -Click the **Files changed** tab on the PR. Hover over a line to see the blue "+" icon. Click it to open a comment box. - -**Plain comment:** Type your feedback and click "Start a review" (first comment) or "Add review comment" (subsequent). - -**Suggested change:** Click the "±" icon in the comment toolbar. Edit the pre-filled code block to your proposed wording. The author can accept your suggestion with one click. +On the PR's **Files changed** tab, hovering over a line displays a blue "+" icon that opens a comment box on click. -## Submitting your review +- **Plain comment.** Type the feedback and click **Start a review** (first comment) or **Add review comment** (subsequent comments). +- **Suggested change.** The "±" icon in the comment toolbar inserts a pre-filled code block. Editing the block to the proposed wording lets the author accept the suggestion with one click. -Click **Finish your review** (upper right of Files changed). Choose: +## Submitting the review -- **Comment** — you've left notes for the author to address. Use this for every review round where you have feedback. The stage does not advance. -- **Approve** — you're satisfied with the document, typically on a backcheck round after the author has addressed your prior comments. **This is what advances the stage.** -- **Request changes** — _not used in this workflow._ Use **Comment** for routine revision cycles. +The **Finish your review** button (upper right of the Files changed tab) opens the submit dialog. The reviewer chooses one of three options. -Click **Submit review.** + -The typical cycle: you leave notes via **Comment**, the author addresses them and pushes revisions, the stage progression bot pings you to backcheck, and you return to submit **Approve** if satisfied (or another **Comment** review if more feedback is needed). +The typical cycle is: leave notes via **Comment** → the author addresses them and pushes revisions → the stage progression bot pings the reviewer to backcheck → the reviewer returns and submits **Approve** if satisfied (or another **Comment** review with additional feedback). -## After you approve +## After approval -The stage progression workflow advances the PR automatically **if you were the reviewer the site admin assigned for the current stage**. The workflow uses per-individual gating: it compares the approver's username to the list of reviewers the admin assigned via the Reviewers sidebar, and only advances the stage when one of those assigned reviewers approves. If you approve a PR you weren't explicitly assigned to, the bot posts a note acknowledging your approval but doesn't advance the stage. +The stage progression workflow advances the PR automatically only if the approver was the reviewer the site administrator assigned for the current stage. The workflow uses per-individual gating: it compares the approver's username to the list of reviewers the administrator assigned via the Reviewers sidebar, and only advances the stage when one of those assigned reviewers approves. An approval from a reviewer who was not assigned to the PR is acknowledged by the bot but does not advance the stage. -If the site admin assigned multiple people at the same stage, the first approval from any of them advances the stage — you don't all need to approve. +If the site administrator assigned multiple people at the same stage, the first approval from any of them advances the stage — all assigned reviewers do not need to approve. -You don't need to do anything further unless someone tags you with a follow-up question. +The reviewer does not need to take further action unless tagged in a follow-up question. -## New commits after you approve +## New commits after approval -If the author pushes new commits after you approve, GitHub dismisses your approval in the UI so the green checkmark disappears. The stage progression bot, however, does **not** reset the stage label — the document stays at its current review stage (e.g., `stage:peer-review`) and the bot pings you to backcheck the revisions. Take another look at the changes and submit another review: **Approve** if you're satisfied, or another **Comment** review with additional feedback. +When the author pushes new commits after a reviewer approves, GitHub dismisses the approval in the UI so the green checkmark disappears. The stage progression bot, however, does not reset the stage label — the document stays at its current review stage (e.g., `stage:peer-review`) and the bot pings the reviewer to backcheck the revisions. The reviewer reviews the changes and submits another review: **Approve** if satisfied, or another **Comment** review with additional feedback. diff --git a/docs/dev/documentation-guide/13-technical-edit.mdx b/docs/dev/documentation-guide/13-technical-edit.mdx index db83a3d8d..0b31f82af 100644 --- a/docs/dev/documentation-guide/13-technical-edit.mdx +++ b/docs/dev/documentation-guide/13-technical-edit.mdx @@ -3,67 +3,101 @@ title: Technical Edit --- import NavContainer from '@site/src/components/NavContainer'; +import ProcessList from '@site/src/components/ProcessList'; +import TableVerticalNoRef from '@site/src/components/TableVerticalNoRef'; # Technical Edit -The technical edit is an AI-assisted editorial review that checks the document for grammar, clarity, tense consistency, terminology, and Section 508 accessibility compliance. It is a required stage on Lanes 1, 2, and 3. A human technical editor can be substituted at the site admin's discretion. +The technical edit is an AI-assisted editorial review that checks the document for grammar, clarity, tense consistency, terminology, and Section 508 accessibility compliance. It is a required stage on Lanes 1, 2, and 3. A human technical editor can be substituted at the site administrator's discretion. ## When it happens -The technical edit occurs after the prior technical review stage approves the PR: - -- **Lane 1** (new document): after Lead Civil approval -- **Lane 2** (major revision): after Lead Civil approval -- **Lane 3** (minor revision): after peer approval - -At this point, the document has already been reviewed for technical accuracy and (for Lanes 1 and 2) technical quality. The technical edit focuses exclusively on editorial quality and accessibility compliance, and reads the source MDX files directly — **no live deploy is needed at this stage**. The document is only deployed to the live site after the technical edit is complete, and that deploy is for the Director review phase (Lane 1 only). +The technical edit occurs after the prior technical review stage approves the PR. + + + +At this point, the document has already been reviewed for technical accuracy and (for Lanes 1 and 2) technical quality. The technical edit focuses exclusively on editorial quality and accessibility compliance, and reads the source MDX files directly — no live deploy is needed at this stage. The document is only deployed to the live site after the technical edit is complete, and that deploy is for the Director review phase (Lane 1 only). ## How it works -1. A team member with access to the AI tooling checks out the PR branch and runs the technical edit. -2. The tool reads all changed MDX files and applies a standardized review prompt committed to the repository at [`.github/ai-review/technical-editor-prompt.md`](https://github.com/USACE-RMC/RMC-Software-Documentation/blob/main/.github/ai-review/technical-editor-prompt.md). The prompt is reproduced in full at the bottom of this chapter so authors and reviewers can see exactly what the AI is being asked to check. -3. The AI posts inline review comments directly on the PR — on specific lines, with severity levels and suggested fixes — exactly like a human reviewer would. -4. The author addresses each comment: pushes fixes, replies to threads, and resolves conversations as they're addressed. -5. When all comments are addressed, the author checks the checkbox in the PR description: `Technical edit comments addressed — ready for Director review`. -6. The stage progression workflow detects the checkbox and advances the PR to the next stage. + -If the technical edit was done by a human or the author isn't available to check the box, a site admin can apply the `admin:advance-to-director` label to the PR as a manual override. The workflow removes the label and advances the stage the same as a checkbox event. +If the technical edit was performed by a human, or the author is unavailable to check the box, a site administrator can apply the `admin:advance-to-director` label to the PR as a manual override. The workflow removes the label and advances the stage the same as a checkbox event. ## Severity levels -The AI assigns one of three severity levels to each comment: - -- 🔴 **Must fix** — errors or accessibility violations (broken Section 508 compliance, factual grammar errors). -- 🟡 **Should fix** — clarity, consistency, or readability issues. -- 🔵 **Suggestion** — stylistic improvements the author may accept or decline. - -The author is expected to address all 🔴 and 🟡 comments. 🔵 suggestions are at the author's discretion — replying "leaving as-is" is a perfectly valid response. - -## What it does NOT review - -Technical accuracy is the peer reviewer's job. Domain conclusions, MDX component syntax, and frontmatter fields are out of scope. +The AI assigns one of three severity levels to each comment. + + + +## What it does not review + +Technical accuracy is the peer reviewer's responsibility. Domain conclusions, MDX component syntax, and frontmatter fields are out of scope for the technical edit. ## Versioning the prompt -The prompt is a versioned file in the repository at `.github/ai-review/technical-editor-prompt.md`. It can be updated over time as the team learns what the AI catches well and what it misses. Each technical-edit run that's noted in the PR can reference the prompt version used, so comments can be traced back to the exact instructions that generated them. +The prompt is a versioned file in the repository at [`.github/ai-review/technical-editor-prompt.md`](https://github.com/USACE-RMC/RMC-Software-Documentation/blob/main/.github/ai-review/technical-editor-prompt.md). It can be updated over time as the team learns what the AI catches well and what it misses. Each technical-edit run noted on the PR can reference the prompt version used, so comments can be traced back to the exact instructions that generated them. ## Fallback to a human editor -A site admin can route any document to a human technical editor instead of (or in addition to) the AI review. The human editor follows the same workflow as peer reviewers and Lead Civils: they're assigned to the PR via the Reviewers sidebar, review the document on the **preview URL** (the technical edit happens before any live deploy), post comments, and submit their review. The author addresses comments the same way. The only difference is that advancement to the next stage requires the human editor to click Approve rather than the author checking the checkbox. +A site administrator can route any document to a human technical editor instead of (or in addition to) the AI review. The human editor follows the same workflow as peer reviewers and Lead Civils: they are assigned to the PR via the Reviewers sidebar, review the document on the preview URL (the technical edit happens before any live deploy), post comments, and submit their review. The author addresses comments the same way. The only difference is that advancement to the next stage requires the human editor to click Approve rather than the author checking the checkbox. ## Who can run the AI review -Anyone on the team with access to the AI tooling can run the technical edit. The output — the PR review comments — is visible to everyone on GitHub regardless of the reviewer's tooling. Only the trigger requires the tooling. - -If nobody with the tooling is available, use the human editor fallback. The site admin coordinates this. +Any team member with access to the AI tooling can run the technical edit. The output — the PR review comments — is visible to everyone on GitHub regardless of the team member's tooling. Only the trigger requires the tooling. If nobody with the tooling is available, the site administrator coordinates a human editor fallback. --- ## The full review prompt -The prompt below is sent to the AI verbatim. Authors who want to understand exactly what the AI will check (and what it has been instructed not to flag) should read this carefully. +The prompt below is sent to the AI verbatim. Authors and reviewers who want to understand exactly what the AI checks (and what it has been instructed not to flag) should read this carefully. ````markdown # RMC Technical Editor Review Prompt @@ -127,4 +161,4 @@ For each finding, produce: - Alternative phrasings that are equally acceptable ```` -If you want to propose changes to the prompt — for example, adding a new style rule the AI has been missing — open a PR against [`.github/ai-review/technical-editor-prompt.md`](https://github.com/USACE-RMC/RMC-Software-Documentation/blob/main/.github/ai-review/technical-editor-prompt.md) and tag a site admin. +Changes to the prompt — for example, adding a new style rule the AI has been missing — are proposed via a PR against [`.github/ai-review/technical-editor-prompt.md`](https://github.com/USACE-RMC/RMC-Software-Documentation/blob/main/.github/ai-review/technical-editor-prompt.md) with a site administrator tagged. diff --git a/docs/dev/documentation-guide/14-director-workflow.mdx b/docs/dev/documentation-guide/14-director-workflow.mdx index 0ff1f4eaf..22126d4aa 100644 --- a/docs/dev/documentation-guide/14-director-workflow.mdx +++ b/docs/dev/documentation-guide/14-director-workflow.mdx @@ -3,46 +3,49 @@ title: Director Workflow --- import NavContainer from '@site/src/components/NavContainer'; +import ProcessList from '@site/src/components/ProcessList'; # Director Workflow -What the RMC Director does when reviewing a new document. The Director's role is intentionally simple: read the document, approve it, move on. The Director only reviews **new documents** (Lane 1). +What the RMC Director does when reviewing a new document. The Director's role is intentionally simple: read the document, approve it, move on. The Director reviews **new documents only** (Lane 1) — major and minor revisions do not require Director approval. ## Prerequisites -1. A GitHub account (sign up at `github.com` if needed). -2. Membership in `@usace-rmc/docs-director` (a site admin adds you; accept the email invitation). +The Director needs a GitHub account and membership in `@usace-rmc/docs-director`. A site administrator handles the team-membership invitation, which the Director accepts via email. This is one-time setup. -One-time setup. +## What the Director is asked to do -## What you will be asked to do +When a new document has passed peer review, Lead Civil review, and the technical edit, a site administrator assigns the Director as a reviewer. GitHub emails the Director. -When a new document has passed peer review, Lead Civil review, and the technical edit, a site administrator assigns you as a reviewer. GitHub emails you. - -Click the link in the email. On the pull request page, scroll through comments to find one from a **site administrator** containing a URL starting with `https://usace-rmc.github.io/RMC-Software-Documentation/`. This is the **live production site** — the same URL readers will use. - -Click it. The document displays with a DRAFT watermark that will be removed after your approval. +The link in the email opens the pull request. The PR comment thread contains a comment from a site administrator with a URL starting with `https://usace-rmc.github.io/RMC-Software-Documentation/`. This is the live production site — the same URL readers will use. The link opens the document with a DRAFT watermark that will be removed after Director approval. :::warning Use the live URL, not the preview URL -Use the live URL posted by the site administrator, not the automatic "Preview deployed" bot comment from earlier in the thread. The live URL is the one that matches what readers will see; the preview URL is for the earlier review stages. +The live URL is the one posted by the site administrator. The "Preview deployed" bot comment from earlier in the thread points to the preview site used by peer reviewers and the Lead Civil; the Director's review happens on the live URL. ::: -Read the document. It has already been reviewed for technical accuracy (peer reviewer), technical quality (Lead Civil), and editorial quality (technical edit). Your review is a final verification that the document meets RMC standards. +The document has already been reviewed for technical accuracy (peer reviewer), technical quality (Lead Civil), and editorial quality (technical edit). The Director's review is a final verification that the document meets RMC standards. ## Approving -1. Back on the PR, click the **Files changed** tab -2. Click **Review changes** (upper right) -3. Select **Approve** -4. Optionally type a note -5. Click **Submit review** +The Director approves through the standard GitHub review workflow. + + -Done. The site administrator handles everything from here. +The site administrator handles every subsequent step — flipping the draft flag, updating the version history, merging, and deploying. ## If something needs fixing -Select **Comment** (not Approve or Request changes) and describe the issue. The author will fix it, and the site admin will ask you to re-review. +If the Director sees an issue that should be fixed before approval, the appropriate action is to submit a **Comment** review (not Approve, not Request changes) describing the issue. The author addresses the comment, and the site administrator coordinates re-review. -For minor suggestions you don't want to block on, select **Approve** and include a note — the site admin will coordinate the follow-up. +For minor suggestions that should not block approval, the Director can select **Approve** and include a note — the site administrator coordinates the follow-up. diff --git a/docs/dev/documentation-guide/15-site-admin-workflow.mdx b/docs/dev/documentation-guide/15-site-admin-workflow.mdx index cf9d87dea..1de50b9e2 100644 --- a/docs/dev/documentation-guide/15-site-admin-workflow.mdx +++ b/docs/dev/documentation-guide/15-site-admin-workflow.mdx @@ -3,136 +3,209 @@ title: Site Admin Workflow --- import NavContainer from '@site/src/components/NavContainer'; +import ProcessList from '@site/src/components/ProcessList'; +import TableVerticalNoRef from '@site/src/components/TableVerticalNoRef'; # Site Admin Workflow -Responsibilities and procedures for site administrators. +Responsibilities and procedures for the site administrator role. ## Responsibilities -1. Assigning reviewers (peer, Lead Civil, Director) at each stage transition -2. Running checkpoint deploys for Lane 1 PRs -3. Running or coordinating the technical edit -4. Preparing final merge commits (flipping the draft flag, updating version history) -5. Merging PRs and approving production deploys -6. Handling Lane 4 (editorial fix) and Lane 5 (dev doc) PRs as sole reviewer -7. Resolving edge cases + ## Daily routine -Check for PRs needing your attention. The stage progression workflow tags `@usace-rmc/docs-admin` at every transition. Filter: `is:open label:"stage:ready-to-merge"` or `is:open review-requested:@me`. +The site administrator monitors PRs that need attention. The stage progression workflow tags `@usace-rmc/docs-admin` at every transition. A useful filter is `is:open label:"stage:ready-to-merge"` or `is:open review-requested:@me`. ## Assigning reviewers -Reviewers are assigned ad-hoc per PR via the Reviewers sidebar (gear icon → type username → select). There are no standing review teams for peer reviewers or Lead Civils. The workflow's transition comment tells you which role to assign next. +Reviewers are assigned ad-hoc per PR via the Reviewers sidebar (gear icon → type username → select). There are no standing review teams for peer reviewers or Lead Civils. The workflow's transition comment identifies which role to assign next. -For Lane 1, you assign up to three people across the lifecycle: the peer reviewer (if the author didn't), the Lead Civil after peer approval, and the Director after the technical edit. +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. -**Per-individual gating.** When you assign 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. You can assign multiple people at the same stage; the first approval from any of them advances the PR. +**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. -If you assigned the wrong person or need to replace someone, remove them from the Reviewers sidebar and add the correct person. The state comment updates automatically. +To replace an assigned reviewer, the site administrator removes them from the Reviewers sidebar and adds the correct person. The state comment updates automatically. ## Running a checkpoint deploy (Lane 1) -After the author marks the technical edit complete (the PR advances to `stage:director-review`), deploy the PR branch to the live site (watermarked) for the Director's review: +After the author marks the technical edit complete (the PR advances to `stage:director-review`), the site administrator deploys the PR branch to the live site (watermarked) for the Director's review. -1. Repo → **Actions** tab → click **Deploy to GitHub Pages** in the sidebar -2. Click **Run workflow** dropdown (upper right) -3. Enter the PR branch name in the **ref** field -4. Click **Run workflow** -5. When the build completes, click **Review deployments** → check `production` → **Approve and deploy** -6. Verify the document on the live URL with the watermark -7. Post a comment on the PR with the live URL so the Director knows where to read + -This is the **first** time the document appears on the live site. The peer review, Lead Civil review, and technical edit all happened earlier on the preview URL or against source files; the live deploy is deferred until the document has passed editorial review. +This is the first time the document appears on the live site. The peer review, Lead Civil review, and technical edit all happened earlier on the preview URL or against source files; the live deploy is deferred until the document has passed editorial review. -Re-deploy whenever the author pushes revisions during Director review. Post a comment noting the update. +The site administrator re-deploys whenever the author pushes revisions during Director review, posting a comment noting the update. ## Running the technical edit -After the preceding review stage approves (the PR advances to `stage:ai-editor-review`), run the AI-assisted technical edit against the PR. If you don't have the necessary tooling, coordinate with a team member who does. **No deploy is required at this stage** — the technical edit reads the source MDX directly. +After the preceding review stage approves (the PR advances to `stage:ai-editor-review`), the site administrator runs the AI-assisted technical edit against the PR. If the necessary tooling is not available locally, the site administrator coordinates with a team member who has it. No deploy is required at this stage — the technical edit reads the source MDX directly. -The AI posts inline review comments. The author addresses them and checks the PR description checkbox to advance the PR, at which point (Lane 1) you'll run the checkpoint deploy. +The AI posts inline review comments. The author addresses them and checks the PR description checkbox to advance the PR, at which point (Lane 1) the site administrator runs the checkpoint deploy. See [Technical Edit](./13-technical-edit.mdx) for the full prompt the AI uses. -**Manual override.** If a human technical editor did the review instead, or the author isn't available to check the checkbox, apply the `admin:advance-to-director` label to the PR. The workflow removes the label and advances the stage the same as a checkbox event, then posts the next-stage instructions. +**Manual override.** If a human technical editor performed the review instead, or the author is unavailable to check the checkbox, the site administrator applies the `admin:advance-to-director` label to the PR. The workflow removes the label and advances the stage the same as a checkbox event, then posts the next-stage instructions. ## Preparing the final merge -When a PR reaches `stage:ready-to-merge`: - -1. Check out the PR branch (locally or via github.dev). -2. In `src/docConfig.js`, change the document's `draft` flag from `true` to `false`. If the document is going active for the first time, also flip `active: true`. -3. Update `00-version-history.mdx` with reviewer and approver names. -4. Commit and push. -5. Merge the PR to `main`. -6. Approve the final production deploy in the Actions tab. - -For Lane 1: `reviewedBy` includes the peer reviewer and Lead Civil; `approvedBy` is the Director. -For Lane 2: `reviewedBy` is the peer reviewer and Lead Civil; `approvedBy` is `-`. -For Lane 3: `reviewedBy` is the peer reviewer; `approvedBy` is `-`. -Lanes 4 and 5: no version history update needed. +When a PR reaches `stage:ready-to-merge`, the site administrator prepares and executes the merge. + + + +Version history fields are populated by lane. + + ## The `review-workflow` commit status -Every documentation PR has a `review-workflow` commit status that branch protection on `main` requires to be `success` before the PR can merge. This is the hard merge gate — nobody, including you, can click the merge button until the bot flips this status to success. The bot manages it automatically: - -| Situation | Status | -|---|---| -| `stage:peer-review` / `stage:lead-civil-review` / `stage:ai-editor-review` / `stage:director-review` | pending | -| `stage:needs-lane` (workflow couldn't detect the lane) | pending | -| `stage:ready-to-merge` (all reviews complete) | success | -| `lane:editorial-fix` or `lane:dev` assigned | success (immediately) | -| Non-docs PR, `CI Build` passed | success | - -If a PR is stuck because `review-workflow` is pending, check the stage label to figure out what review is outstanding. If a PR is stuck because `review-workflow` is missing entirely (never got set), the lane-detection step probably failed — apply a `lane:*` label manually to re-trigger the workflow. +Every documentation PR has a `review-workflow` commit status that branch protection on `main` requires to be `success` before the PR can merge. This is the hard merge gate — no participant, including the site administrator, can click the merge button until the bot flips this status to success. The bot manages the status automatically. + + + +If a PR is stuck because `review-workflow` is pending, the stage label indicates what review is outstanding. If a PR is stuck because `review-workflow` is missing entirely (never got set), lane detection probably failed — the site administrator applies a `lane:*` label manually to re-trigger the workflow. ## Approving deploys -Every deploy pauses at the production environment gate. You receive an email. Navigate to Actions → the workflow run → Review deployments → check `production` → Approve and deploy. +Every deploy pauses at the production environment gate. The site administrator receives an email. Navigating to Actions → the workflow run → Review deployments → check `production` → Approve and deploy releases the deploy. A Lane 1 document may involve multiple deploys: one checkpoint after the technical edit completes (for Director review), optional re-deploys during Director review if the author pushes fixes, and one final deploy after merge. ## Handling Lane 4 and Lane 5 PRs -Lane 4 (editorial fix) and Lane 5 (dev doc) PRs skip formal review. You are the reviewer, approver, and merger: +Lane 4 (editorial fix) and Lane 5 (dev doc) PRs skip formal review. The site administrator is the reviewer, approver, and merger. -1. Click the preview URL to see the change -2. Review the Files changed tab -3. Approve, merge, approve the deploy + -The `review-workflow` commit status is flipped to success immediately on lane assignment, so the merge button is enabled as soon as CI finishes. +The `review-workflow` commit status flips to success immediately on lane assignment, so the merge button is enabled as soon as CI finishes. ## Edge cases -**Wrong lane:** Remove the current `lane:*` label, apply the correct one. The workflow re-initializes. - -**Branch starts with `docs/` but doesn't match a sub-prefix:** The workflow applies `stage:needs-lane` and tags you. Apply the correct `lane:*` label. - -**Documentation change pushed to a non-`docs/` branch:** The workflow intercepts this at PR open time regardless of branch name, because it detects changes to files under `docs/`. If the content is entirely under `docs/dev/`, it auto-assigns `lane:dev`. Otherwise it applies `stage:needs-lane` and tags you to assign the correct lane manually. Optionally ask the author to rename the branch next time for clarity. - -**Non-documentation PR with no lane comments:** Expected behavior. PRs that don't touch `docs/` are silently skipped by the lane workflow and pass the `review-workflow` status check via `CI Build`. This is normal for infrastructure, tooling, and dependency PRs. - -**Unresponsive reviewer:** Ping them on the PR, or remove them from the Reviewers sidebar and assign someone else. The state comment updates automatically. - -**Drive-by approval from an unassigned reviewer:** The workflow posts a note logging the approval but does not advance the stage. If the unassigned approver should actually be advancing the PR, add them as a reviewer via the Reviewers sidebar and ask them to re-approve — the new approval will then match the assigned list and advance the stage. - -**Author pushes new commits during an active review:** Normal and expected. The workflow does not reset the stage. The bot re-sets the `review-workflow` commit status on the new head SHA and pings the assigned reviewer(s) to backcheck. - -**Stale checkpoint deploy:** If the live URL shows outdated content, re-run the checkpoint deploy and post a comment. - -**Build fails on checkpoint deploy:** Coordinate with the author to fix the branch. - -**Build fails after merge to main:** Push a hotfix to `main` or revert the merge. Re-run the deploy. Note that `deploy.yml` filters by paths — a merge that doesn't touch any site-affecting files does not trigger a redeploy, so a broken workflow or a change to the planning folder won't break the live site. - -**Need to force a production redeploy:** Go to Actions → Deploy to GitHub Pages → Run workflow, specify the ref (usually `main`), and approve at the production gate. This is the escape hatch when the path filter would otherwise skip a merge that actually needs to ship. - -## Onboarding new site admins - -1. Clone the repo, confirm local build works. -2. Read these Documentation Guide chapters (09 through 15). -3. Shadow an existing admin through one full PR lifecycle. -4. Practice on a Lane 4 editorial fix PR. + + +## Onboarding new site administrators + + From 54ebe4292e8f96a8c630249c98288702c08e11b6 Mon Sep 17 00:00:00 2001 From: Adam Gohs Date: Tue, 19 May 2026 12:06:31 -0400 Subject: [PATCH 7/7] Link to Review Lanes from Step 1 of new-doc walkthrough Add a tip admonition in Step 1 pointing readers to Review Lanes so they can see all five branch prefixes available and pick the right one. Also redirects readers who actually want to do a revision (not a new doc) to the Versioning System chapter. --- .../04-creating-new-document-walkthrough.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/dev/documentation-guide/04-creating-new-document-walkthrough.mdx b/docs/dev/documentation-guide/04-creating-new-document-walkthrough.mdx index aaf5c8890..4763caa39 100644 --- a/docs/dev/documentation-guide/04-creating-new-document-walkthrough.mdx +++ b/docs/dev/documentation-guide/04-creating-new-document-walkthrough.mdx @@ -178,6 +178,10 @@ Before you begin, gather and prepare the following: The `main` branch is protected — you cannot push directly to it. All new documents are authored on a feature branch that gets merged via a pull request. For a new document, the branch prefix is **`docs/new/`** — this routes the PR to Lane 1 (the full review workflow with peer, Lead Civil, technical edit, and Director stages). +:::tip Not creating a new document? +Five branch prefixes are available, each routing to a different review lane (new document, major revision, minor revision, editorial fix, dev docs). See [Review Lanes](./10-review-lanes.mdx) for the full list and how each lane works. This chapter covers Lane 1 only — for revisions to an existing document, see [Versioning System](./02-versioning-system.mdx) instead. +::: + **Branch naming:** `docs/new/` where the slug describes the document. Use lowercase with hyphens. **Examples:**