Document review and approval workflow; refresh docConfig, CLAUDE.md, README#118
Merged
AdamGohs merged 7 commits intoMay 19, 2026
Merged
Conversation
- 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
- 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
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.
- 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
|
📋 Assigned reviewers for this PR
The first approval from any assigned reviewer at the current stage advances the PR. Approvals from non-assigned reviewers are logged but do not advance the stage. |
github-actions
Bot
added
lane:dev
|
📋 Lane: Dev Doc No formal review required. @usace-rmc/docs-admin please review, merge, and approve the deploy. |
|
📄 Preview deployed for commit https://usace-rmc.github.io/RMC-Software-Documentation-Previews/pr-118/ This preview updates automatically when new commits are pushed. Deleted when the PR closes. |
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.
- 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.
|
@usace-rmc/docs-admin please eyeball the new changes before merging — the bot has re-set the |
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.
|
@usace-rmc/docs-admin please eyeball the new changes before merging — the bot has re-set the |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Brings the Documentation Guide, README.md, and CLAUDE.md up to date with the review and approval workflow infrastructure that's been in place since PRs #107–#117 (preview builds, lane labels, stage progression, per-individual reviewer gating, the
review-workflowmerge gate, the AI-assisted technical edit, and thesrc/docConfig.jscentral registry).Auto-routed to lane:dev by content-based detection — every documentation file changed in this PR is under
docs/dev/.Affected documents
README.md(rewritten — Skills + MCP sections removed; Review Workflow section added)CLAUDE.md(path fix, missing npm scripts,src/docConfig.jsdoc, branching strategy, drop user-facing Skills section)scripts/generateSidebars.js(mainIdsandappendixIdsupdated for new chapter numbering)Changes Made
New chapters (
docs/dev/documentation-guide/)docs/new/,docs/major/,docs/minor/,docs/fix/,docs/dev/) and what each lane requiresRenames
09-appendix-a-source-code-structure.mdx→16-…10-appendix-b-build-process-overview.mdx→17-…11-appendix-c-search-configuration.mdx→18-…URLs are unchanged because Docusaurus strips numeric prefixes.
Targeted fixes to existing chapters
02-versioning-system.mdxStep 7: replaced the "commit to main / push origin main" instructions (which would fail against branch protection) with the proper branch-and-PR flow usingdocs/major//docs/minor/prefixes03-project-structure.mdx: addedsrc/docConfig.jsto the tree as a Tier 1 contributor-edit file with full description of the active/draft flag semantics; clarified thatsrc/draftDocs.jsis now a shim16-appendix-a-source-code-structure.mdx: rewrote thedraftDocs.jssection to describedocConfig.jsas the source of truth; replaced the outdatedDocItemcode example with the current version-aware watermark implementation (usesuseLocation()andlatestVersions.json)00-introduction.mdx: added the seven new chapters to the guide organization; rewrote the Common Contribution Workflows section to reference branch prefixes01-getting-started.mdx: updated the Appendix B cross-link for the renameREADME.md
Removed the user-facing Claude Code Skills section and the MCP Servers section. The skills are still in
.claude/skills/for team members who use Claude Code, but they're not surfaced to the broader team. Added a "Review and Approval Workflow" section showing the five branch prefixes, their lanes, and theCI Build+review-workflowmerge gate.CLAUDE.md
docs/00-documentation-guide/→docs/dev/documentation-guide/pathnpm runcommands (report-map,image-dims,generate-toc) and noted theDOCS_MODEenvironment variablesrc/docConfig.jsas the central active/draft registry/qc-reviewor/build(the latter doesn't exist as a skill)Commits
Update CLAUDE.md for review workflow and docConfig.js— also includes the appendix renames (they were staged fromgit mvbefore this commit)Fix Documentation Guide gaps for branching and docConfig.jsAdd seven review-process chapters to Documentation GuideRefresh README for review workflow and remove skill referencesTesting Performed
npm run sidebarssucceeds — all seven new chapters and the renamed appendices appear in the sidebar in the expected ordernpm run buildsucceeds with no errors or warnings related to the changes (only the pre-existinglatestVersionswarning forrmc-totalrisk/verification-reportwhich is unrelated)Breaking Changes
URLs for the renamed appendices are unchanged.
Pre-submission checklist
docs/dev/00-version-history.mdxif this change warrants a version entry — N/A, the Documentation Guide does not maintain a version-history tableTechnical edit (Lane 1 only)
N/A for Lane 5.
Notes for reviewers
.github/ai-review/technical-editor-prompt.md.docs/dev/github-workflows/chapters to reflect the RMC-specific workflow) was deferred for a separate discussion — those chapters appear to be intended as repo-agnostic guidance.