Skip to content

Commit 41122ac

Browse files
authored
Merge pull request #118 from USACE-RMC/docs/dev/documentation-guide-review-workflow-updates
Document review and approval workflow; refresh docConfig, CLAUDE.md, README
2 parents 651adda + 54ebe42 commit 41122ac

18 files changed

Lines changed: 1374 additions & 511 deletions

‎CLAUDE.md‎

Lines changed: 59 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -5,42 +5,66 @@ This is the official documentation site for the **RMC (Risk Management Center) s
55
## Quick Commands
66

77
```bash
8-
npm start # Start dev server (runs all generation scripts first)
9-
npm run build # Build static site for production
10-
npm run counters # Generate figure/table/equation counters
11-
npm run sidebars # Generate sidebar navigation from MDX files
12-
npm run versions # Extract version metadata
13-
npm run report-map # Create reportIdMap.js for document routing
8+
npm start # Start dev server (runs all generation scripts first)
9+
npm run build # Build static site for production
10+
npm run sidebars # Generate sidebars.js from MDX folder structure
11+
npm run counters # Generate figure/table/equation counters
12+
npm run versions # Extract version metadata
13+
npm run report-map # Generate reportIdMap.js for document routing
14+
npm run image-dims # Generate image dimension metadata
15+
npm run generate-toc # Generate Event Tree Database TOC data
1416
```
1517

18+
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`.
19+
1620
## Project Structure
1721

1822
```
1923
docs/ # Documentation content (MDX files)
2024
├── desktop-applications/ # LifeSim, RMC-TotalRisk, RMC-RFA, RMC-BestFit
2125
├── toolbox-technical-manuals/ # Internal Erosion, Overtopping, Risk Calcs, Seismic
2226
├── web-applications/ # RRFT, LST, DST
23-
└── 00-documentation-guide/ # Contributor guide and style reference
27+
└── dev/ # Developer-facing docs
28+
├── documentation-guide/ # Contributor guide and style reference
29+
├── github-workflows/ # GitHub workflow SOP
30+
├── architecture/ # Web app architecture references
31+
├── ai-development/ # AI-assisted development guidance
32+
├── python-quickstart-guide/
33+
└── dst/ # DST developer + UI style guides
2434
2535
src/
2636
├── components/ # 40+ custom React components (Figure, Table*, Citation, etc.)
27-
├── contexts/ # ReportIdContext for version/document tracking
37+
├── contexts/ # ReportIdContext, TourContext
2838
├── css/ # Tailwind & component styles
29-
└── theme/ # Docusaurus theme customizations
39+
├── theme/ # Docusaurus theme customizations (DocItem watermark, Layout, etc.)
40+
├── docConfig.js # Central source of truth for active/draft flags
41+
└── draftDocs.js # Thin shim around docConfig.js (consumed by DocItem)
3042
31-
scripts/ # Build automation (sidebar, counter, version generation)
43+
scripts/ # Build automation (sidebars, counters, versions, etc.)
3244
static/ # Static assets and auto-generated metadata
45+
.github/ # CODEOWNERS, PR template, workflows, AI review prompt
46+
planning/ # Implementation specs for cross-cutting changes
3347
```
3448

3549
## Auto-Generated Files (DO NOT EDIT)
3650

3751
These files are regenerated by build scripts:
3852
- `sidebars.js` - Generated from docs/ structure
3953
- `src/reportIdMap.js` - Generated from MDX frontmatter
54+
- `src/imageDimensions.js` - Generated from images in static/figures/
4055
- `static/counters/` - Figure/table/equation numbering
4156
- `static/versions/` - Version metadata
4257
- `src/data/` - Event tree TOC data
4358

59+
## Document Active/Draft Flags
60+
61+
`src/docConfig.js` is the central registry for every published document tile. Each entry has two orthogonal flags:
62+
63+
- `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.
64+
- `draft`: `true` renders a diagonal "DRAFT" watermark on the **latest version only** of the doc (older versions stay unwatermarked). `false` means no watermark.
65+
66+
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).
67+
4468
## Key Patterns
4569

4670
### MDX Document Structure
@@ -78,6 +102,26 @@ Content with <Figure figKey="fig1" src="path" alt="text" caption="..." />
78102
- Version paths: `docs/{category}/{app}/{type}/v{major}.{minor}/`
79103
- Special files: `00-document-info.mdx`, `00-version-history.mdx`
80104

105+
## Branching and Review Workflow
106+
107+
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:
108+
109+
| Prefix | Lane | Reviews required |
110+
|---|---|---|
111+
| `docs/new/` | New document | Peer → Lead Civil → Technical edit → Director |
112+
| `docs/major/` | Major revision (new major version) | Peer → Lead Civil |
113+
| `docs/minor/` | Minor revision (new minor version) | Peer |
114+
| `docs/fix/` | Editorial fix | None (admin self-merge) |
115+
| `docs/dev/` | Dev docs (anything under `docs/dev/`) | None (admin self-merge) |
116+
117+
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.
118+
119+
Branch protection on `main` requires two status checks:
120+
- `CI Build` — runs `npm run build` on every PR
121+
- `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`)
122+
123+
Full details: [docs/dev/documentation-guide/](docs/dev/documentation-guide/) chapters 09–15.
124+
81125
## Code Style
82126

83127
- Prettier: 150 char line width, single quotes, trailing commas
@@ -89,39 +133,24 @@ Content with <Figure figKey="fig1" src="path" alt="text" caption="..." />
89133
- Do NOT include "Co-Authored-By: Claude", "Claude Code", or any AI/assistant attribution in commit messages
90134
- Keep commit messages concise and focused on the changes made
91135

92-
## Claude Code Skills
93-
94-
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`).
95-
96-
### Available Skills
97-
98-
**Git**: `/commit`, `/push`, `/commit-push`, `/pr`, `/review-pr`
99-
**Page verification**: `/smoke-test`, `/review-responsive`, `/review-page`
100-
**Quality**: `/check-accessibility`, `/check-performance`, `/lint-fix`
101-
**Documentation**: `/qc-review`, `/build`, `/check-links`, `/check-components`
102-
**Scaffolding**: `/new-doc`
103-
104-
See `.claude/skills/{name}/SKILL.md` for full documentation of each skill.
136+
## QC Reviews
105137

106-
## QC Reviews & Technical Edits
107-
108-
Use `/qc-review` skill or the QC prompt template at [qc/qc-prompt.md](qc/qc-prompt.md) for AI-assisted document reviews.
109-
110-
### Review Levels
138+
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:
111139

112140
| Level | Name | When to Use |
113141
|-------|------|-------------|
114142
| 1 | Syntax & Grammar | No source PDF available; check MDX syntax, components, grammar only |
115143
| 2 | Source Comparison | Source PDF available; Level 1 + verify MDX matches source exactly |
116144
| 3 | Technical Edit | Source PDF available; Levels 1 & 2 + suggest content improvements |
117145

118-
### Key Rules
119-
146+
Key rules:
120147
- **Level 1**: Do NOT suggest rewording or technical changes—syntax and grammar only
121148
- **Level 2**: Do NOT suggest improvements beyond matching the source document
122149
- **Level 3**: Full editorial suggestions allowed; mark these as "Editorial" category with "Suggestion" severity
123150
- All levels: Do NOT edit MDX files directly—output findings to `qc/` only
124151

152+
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.
153+
125154
## Requirements
126155

127156
- Node.js >= 18.0

‎README.md‎

Lines changed: 14 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ The project includes:
1212

1313
The project is organized to support easy contribution, internal consistency, and extensibility across future RMC documentation needs.
1414

15-
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/)
15+
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/).
1616

1717
The guide includes:
1818

@@ -21,51 +21,25 @@ The guide includes:
2121
- Tailwind utility conventions and shared styles
2222
- Table formatting and counter file integration
2323
- Versioning strategy and linking guidelines
24+
- The full review and approval workflow for all documentation changes
2425

25-
## Claude Code Skills
26+
## Review and Approval Workflow
2627

27-
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.
28+
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:
2829

29-
### Git & Repository
30+
| Branch prefix | Lane | Reviews required |
31+
|---|---|---|
32+
| `docs/new/` | New document | Peer → Lead Civil → Technical edit → Director |
33+
| `docs/major/` | Major revision (new major version) | Peer → Lead Civil → Technical edit |
34+
| `docs/minor/` | Minor revision (new minor version) | Peer → Technical edit |
35+
| `docs/fix/` | Editorial fix | None (admin self-merge) |
36+
| `docs/dev/` | Dev docs (anything under `docs/dev/`) | None (admin self-merge) |
3037

31-
| Skill | Description |
32-
|-------|-------------|
33-
| `/commit` | Stage changes and create a git commit following project conventions |
34-
| `/push` | Push current branch to remote with safety checks |
35-
| `/commit-push` | Commit and push in a single operation |
36-
| `/pr` | Create a GitHub pull request with auto-generated title and description |
37-
| `/review-pr` | Review a pull request for code quality, MDX patterns, and documentation standards |
38+
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.
3839

39-
### Page Verification & Quality
40+
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/).
4041

41-
| Skill | Description |
42-
|-------|-------------|
43-
| `/smoke-test` | Quick health check — page loads, no console errors, no broken images |
44-
| `/review-responsive` | Screenshot and analyze a page at 7 device viewports (desktop through phone) |
45-
| `/review-page` | Full page audit combining Lighthouse scores with responsive design review |
46-
| `/check-accessibility` | Section 508 / WCAG AA compliance audit using Lighthouse + Playwright |
47-
| `/check-performance` | Lighthouse performance audit with Core Web Vitals and resource analysis |
48-
| `/lint-fix` | Run ESLint, auto-fix issues, and provide guidance for remaining problems |
49-
50-
### Documentation & QC
51-
52-
| Skill | Description |
53-
|-------|-------------|
54-
| `/qc-review` | Run a QC review at Level 1, 2, or 3 on an MDX document (wraps `qc/qc-prompt.md`) |
55-
| `/build` | Run the Docusaurus production build and analyze errors/warnings |
56-
| `/check-links` | Scan MDX files for broken references, missing images, and orphaned keys |
57-
| `/check-components` | Validate custom component usage (props, imports, key uniqueness) in MDX files |
58-
59-
### MCP Servers
60-
61-
The following MCP servers enhance skill capabilities:
62-
63-
- **Playwright** — Browser automation for screenshots, responsive testing, and smoke tests
64-
- **Lighthouse** — Performance, accessibility, SEO, and best practices auditing
65-
- **ESLint** — JavaScript linting via MCP
66-
- **Context7** — Library documentation lookup
67-
- **Sequential Thinking** — Multi-step reasoning for complex analysis
68-
- **GitHub** — GitHub API integration for PR and issue workflows
42+
## Contact
6943

7044
For questions or support, contact the RMC documentation team:
7145

‎docs/dev/documentation-guide/00-introduction.mdx‎

Lines changed: 50 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -137,11 +137,21 @@ The documentation guide is structured to take you from setup through advanced us
137137

138138
8. **[Troubleshooting & FAQ](./08-troubleshooting-faq.mdx)** - Solutions to common problems
139139

140+
### Review and Approval Process
141+
142+
9. **[Review and Approval Process Overview](./09-review-and-approval-overview.mdx)** - Roles, lanes, the merge gate, and the draft watermark
143+
10. **[Review Lanes](./10-review-lanes.mdx)** - Branch prefixes and which review stages apply to each lane
144+
11. **[Author Workflow](./11-author-workflow.mdx)** - From branch creation to publication
145+
12. **[Reviewer Workflow](./12-reviewer-workflow.mdx)** - For peer reviewers and RMC Lead Civils
146+
13. **[Technical Edit](./13-technical-edit.mdx)** - AI-assisted editorial review (includes the full prompt)
147+
14. **[Director Workflow](./14-director-workflow.mdx)** - Final approval for new documents
148+
15. **[Site Admin Workflow](./15-site-admin-workflow.mdx)** - Reviewer assignment, checkpoint deploys, merge prep
149+
140150
### Appendices (Advanced Topics)
141151

142-
- **[Appendix A: Source Code Structure](./09-appendix-a-source-code-structure.mdx)** - Deep dive into project architecture
143-
- **[Appendix B: Build Process Overview](./10-appendix-b-build-process-overview.mdx)** - How automation scripts work behind the scenes
144-
- **[Appendix C: Search Configuration](./11-appendix-c-search-configuration.mdx)** - Algolia search setup (admin-level)
152+
- **[Appendix A: Source Code Structure](./16-appendix-a-source-code-structure.mdx)** - Deep dive into project architecture
153+
- **[Appendix B: Build Process Overview](./17-appendix-b-build-process-overview.mdx)** - How automation scripts work behind the scenes
154+
- **[Appendix C: Search Configuration](./18-appendix-c-search-configuration.mdx)** - Algolia search setup (admin-level)
145155

146156
---
147157

@@ -258,20 +268,24 @@ This is regular text with **bold** and _italic_ formatting.
258268

259269
## Common Contribution Workflows
260270

271+
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.
272+
261273
### Workflow 1: Convert Existing Word Document
262274

263275
**Use case:** You have an existing RMC document in Word format that needs to be converted to MDX.
264276

265277
**Steps:**
266278

267-
1. Place Word document in `static/source-documents/`
268-
2. Run DOCX converter script to generate MDX files
269-
3. Review and refine generated MDX files
270-
4. Add generated files to appropriate `docs/` folder
271-
5. Test locally with `npm start`
272-
6. Commit changes to Git
279+
1. Create a `docs/new/<slug>` branch off `main`.
280+
2. Place the Word document in `static/source-documents/`.
281+
3. Run the DOCX converter script to generate MDX files.
282+
4. Review and refine generated MDX files.
283+
5. Add generated files to the appropriate `docs/` folder.
284+
6. Register the document in `src/docConfig.js` with `active: false, draft: true`.
285+
7. Test locally with `npm start`.
286+
8. Commit, push the branch, and open a pull request. The review workflow auto-assigns Lane 1 (peer → Lead Civil → technical edit → Director).
273287

274-
**Typical time:** 1-3 hours depending on document complexity
288+
**Typical time:** 1-3 hours depending on document complexity.
275289

276290
---
277291

@@ -283,19 +297,20 @@ This is regular text with **bold** and _italic_ formatting.
283297

284298
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).
285299

286-
The walkthrough includes folder setup, asset organization, administrator coordination, testing procedures, and complete examples.
300+
The walkthrough includes folder setup, asset organization, testing procedures, and complete examples.
287301

288302
:::
289303

290304
**High-Level Steps:**
291305

292-
1. Determine folder location based on hierarchy (see [Complete Walkthrough](./04-creating-new-document-walkthrough.mdx))
293-
2. Create all folder structures (docs/, static/figures/, static/videos/, static/bibliographies/)
294-
3. Add supporting assets (figures, videos, bibliography)
295-
4. Create MDX files (using DOCX converter or manually)
296-
5. Test locally with `npm start`
297-
6. Contact site administrator for deployment coordination
298-
7. Commit changes to repository after approval
306+
1. Create a `docs/new/<slug>` branch off `main`.
307+
2. Determine folder location based on hierarchy (see [Complete Walkthrough](./04-creating-new-document-walkthrough.mdx)).
308+
3. Create all folder structures (`docs/`, `static/figures/`, `static/videos/`, `static/bibliographies/`).
309+
4. Add supporting assets (figures, videos, bibliography).
310+
5. Create MDX files (using the DOCX converter or manually).
311+
6. Register the document in `src/docConfig.js` with `active: false, draft: true`.
312+
7. Test locally with `npm start`.
313+
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)).
299314

300315
**For detailed instructions, templates, real-world examples, and troubleshooting, use the [comprehensive walkthrough](./04-creating-new-document-walkthrough.mdx).**
301316

@@ -305,23 +320,27 @@ The walkthrough includes folder setup, asset organization, administrator coordin
305320

306321
**Use case:** You need to update an existing document for a new software version or to correct errors.
307322

308-
**For minor edits (typos, small clarifications):**
323+
**For typos and editorial fixes (Lane 4):**
324+
325+
1. Create a `docs/fix/<slug>` branch off `main`.
326+
2. Edit the existing version's MDX files directly.
327+
3. Test locally.
328+
4. Commit, push, and open a PR. The site admin will review and merge — no formal peer review required.
329+
330+
**For minor revisions / new minor version (Lane 3):**
309331

310-
1. Edit the existing version's MDX files directly
311-
2. Test locally
312-
3. Commit changes
332+
1. Create a `docs/minor/<slug>-v<version>` branch off `main`.
333+
2. Create the new version folder (e.g., `v1.1/`) by copying the previous version.
334+
3. Mirror the version structure for figures, bibliography, and source documents.
335+
4. Make your updates and flip `draft: true` on the document's entry in `src/docConfig.js`.
336+
5. Test locally.
337+
6. Commit, push, and open a PR. The workflow assigns Lane 3 (peer review → technical edit).
313338

314-
**For major updates (new features, substantial changes):**
339+
**For major revisions / new major version (Lane 2):**
315340

316-
1. Create new version folders (e.g., `v1.1/`)
317-
2. Copy all files from previous version
318-
3. Make updates to the new version
319-
4. Add new images to corresponding `static/figures/` version folder
320-
5. Update `bib.json` if needed
321-
6. Test locally
322-
7. Commit changes
341+
Same as Lane 3 but on a `docs/major/<slug>-v<version>` branch. The workflow adds an RMC Lead Civil review stage between peer review and the technical edit.
323342

324-
**Typical time:** 30 minutes to 2 hours depending on scope
343+
**Typical time:** 30 minutes to a few hours depending on scope. Review turnaround adds days; plan accordingly.
325344

326345
---
327346

0 commit comments

Comments
 (0)