Skip to main content
U.S. Army Corps of Engineers
®
US Army Corps of EngineersInstitute for Water Resources, Risk Management Center
Developer Resources

Documentation Guide

Welcome to the RMC Software Documentation Project​

This guide will help you contribute to the RMC Software Documentation website - a comprehensive resource for USACE Risk Management Center software tools, technical manuals, and web applications.

Whether you're converting existing Word documents to MDX format or creating new documentation from scratch, this guide provides everything you need to get started and become a productive contributor.

Who This Guide Is For​

This documentation guide is designed for:

  • Technical Writers creating and maintaining documentation
  • Software Developers documenting their tools and applications
  • Subject Matter Experts contributing technical content
  • Project Contributors writing or converting documentation
  • Anyone converting Word/PDF documents to MDX format

No programming experience is required! While some programming knowledge is helpful, this guide is written for beginners and assumes you're starting with basic computer skills.

What You'll Learn​

By following this guide, you will learn how to:

✅ Set up your development environment

  • Install Node.js, Visual Studio Code, and Git
  • Clone the project repository
  • Run the documentation site locally on your computer

✅ Understand the project structure

  • Navigate the folder hierarchy
  • Know which files to edit and which to avoid
  • Organize documentation by software type and version

✅ Write content in MDX (Markdown + JSX)

  • Use Markdown syntax for text formatting
  • Import and use React components for figures, tables, and equations
  • Create properly structured documentation pages

✅ Use React components in your documentation

  • Insert numbered figures with automatic cross-references
  • Create tables with complex layouts
  • Add mathematical equations using LaTeX
  • Manage citations and bibliographies
  • Organize content with tabs, lists, and callouts

✅ Manage document versions

  • Create new versions of documentation
  • Understand version folder structure
  • Use the automated version selector

✅ Follow best practices

  • Name files and folders consistently
  • Structure documents for easy navigation
  • Write accessible and user-friendly documentation
  • Troubleshoot common issues

What This Guide Does NOT Cover​

This guide focuses on contributing content to the documentation site. It does not cover:

❌ Creating new React components (advanced topic - requires React/JavaScript knowledge)
❌ Modifying build scripts (administrator-level task)
❌ Configuring Docusaurus plugins (administrator-level task)
❌ Deploying to production (administrator-only task - site deployment is restricted)
❌ Customizing Tailwind CSS (advanced styling - coordinate with administrators)
❌ Setting up Algolia search (administrator-level configuration)

Focus: This guide keeps you focused on what matters most - writing great documentation.

Prerequisites​

Before you begin, you should have:

  • Basic computer skills - Comfortable navigating files and folders
  • Familiarity with text editing - Ability to edit text files
  • Access to a computer - Windows, Mac, or Linux
  • Time for setup - Initial setup takes 30-60 minutes

Optional but helpful:

  • Experience with Markdown (you'll learn it in this guide)
  • Basic understanding of HTML/web pages
  • Familiarity with Git/version control

Not required:

  • Programming experience
  • React or JavaScript knowledge
  • Web development background

How This Guide Is Organized​

The documentation guide is structured to take you from setup through advanced usage:

Getting Started​

  1. Getting Started - Install software, clone the repository, run the site locally

Understanding the Project​

  1. Versioning System - How document versioning works
  2. Project Structure - Folder organization and what you should (and shouldn't) edit

Creating Content​

  1. Creating a New Document (Walkthrough) - Step-by-step guide for new documents
  2. DOCX Converter - Convert Word documents to MDX format
  3. Creating and Editing Pages - Comprehensive MDX guide with Markdown and JSX syntax
  4. React Components - Complete component library reference

Reference Materials​

  1. Troubleshooting & FAQ - Solutions to common problems

Review and Approval Process​

  1. Review and Approval Process Overview - Roles, lanes, the merge gate, and the draft watermark
  2. Review Lanes - Branch prefixes and which review stages apply to each lane
  3. Author Workflow - From branch creation to publication
  4. Reviewer Workflow - For peer reviewers and RMC Lead Civils
  5. Technical Edit - AI-assisted editorial review (includes the full prompt)
  6. Director Workflow - Final approval for new documents
  7. Site Admin Workflow - Reviewer assignment, checkpoint deploys, merge prep

Appendices (Advanced Topics)​

Quick Start Path​

If you're eager to start contributing, follow this path:

  1. Step 1: Setup (Getting Started)

    • Install Node.js, VS Code, and Git
    • Create a GitHub account and request collaborator access
    • Clone the repository to a local folder (avoid OneDrive locations)
    • Run npm install and npm start
    • View the site at http://localhost:3000

  2. Step 2: Explore (Project Structure)

    • Take the guided site tour on the live site to see all features in action
    • Understand where files go
    • Learn what you can and can't edit
    • Navigate the docs/ folder structure

  3. Step 3: Create (Creating and Editing Pages)

    • Learn Markdown syntax
    • Create your first MDX file
    • Import and use React components

  4. Step 4: Polish (React Components)

    • Add figures, tables, and equations
    • Use advanced components
    • Format content professionally

  5. Ongoing: Refer to Troubleshooting as needed

Key Concepts to Understand​

Before diving in, familiarize yourself with these core concepts:

Guided Site Tour​

The RMC Software Documentation site includes a guided site tour that walks you through the key features of the site. The tour highlights the navigation bar, search, sidebar, table of contents, breadcrumbs, document info pages, version history, figures, tables, citations, and more.

How to start the tour:

  • Visit the homepage and click the "Take a tour" button located above the category cards.
  • The tour will guide you through 15 interactive steps, automatically navigating between pages to show each feature in context.

Tour controls:

  • Next / Back buttons or Arrow keys to navigate between steps
  • Escape or the Close (X) button to exit at any time
Recommended for New Contributors

If this is your first time visiting the site, take the guided tour before diving into this guide. It provides a quick visual overview of all the features you'll be working with.

Docusaurus​

Docusaurus is a modern static website generator built on React. It takes your Markdown/MDX files and converts them into a fast, user-friendly documentation website with:

  • Automatic navigation sidebar
  • Search functionality
  • Version management
  • Dark mode support
  • Mobile responsiveness
  • Guided site tour for new users

What you need to know: Docusaurus handles the technical website stuff automatically. You focus on writing content.

MDX (Markdown + JSX)​

MDX is a file format that combines:

  • Markdown - Simple text formatting syntax (headings, lists, bold, italic, etc.)
  • JSX - React component syntax that lets you insert interactive elements

Example:

## This is a Markdown heading

This is regular text with **bold** and _italic_ formatting.

<Figure figKey="figure-1" src="/figures/my-diagram.png" caption="This is a React component embedded in Markdown" />

What you need to know: Write most of your content in Markdown, and use JSX components for figures, tables, and special formatting.

React Components​

React components are reusable UI elements that you can insert into your MDX files. They handle complex layouts and automatic numbering.

Examples:

  • <Figure> - Numbered figure with caption and auto-generated figure number
  • <TableVertical> - Multi-column table with complex spanning
  • <Equation> - Numbered mathematical equation with LaTeX formatting
  • <Citation> - Inline citation reference linked to bibliography

What you need to know: You don't need to understand how components work internally. Just learn the syntax to use them (covered in this guide).

Version Control with Git​

Git is a version control system that tracks changes to files over time. GitHub is a web platform for hosting Git repositories.

What you need to know:

  • Git keeps a history of all changes
  • You can always revert if something breaks
  • Multiple people can work simultaneously without conflicts
  • GitHub Desktop provides a user-friendly interface

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 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. Create a docs/new/<slug> 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.

Workflow 2: Create New Documentation from Scratch​

Use case: You're creating brand new documentation for software or a technical manual.

Comprehensive Walkthrough Available

For a detailed, step-by-step guide to creating a new document from scratch, see Chapter 04: Creating a New Document - Complete Walkthrough.

The walkthrough includes folder setup, asset organization, testing procedures, and complete examples.

High-Level Steps:

  1. Create a docs/new/<slug> branch off main.
  2. Determine folder location based on hierarchy (see Complete Walkthrough).
  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).

For detailed instructions, templates, real-world examples, and troubleshooting, use the comprehensive walkthrough.

Workflow 3: Update Existing Documentation​

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

For typos and editorial fixes (Lane 4):

  1. Create a docs/fix/<slug> 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. Create a docs/minor/<slug>-v<version> 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 revisions / new major version (Lane 2):

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.

Typical time: 30 minutes to a few hours depending on scope. Review turnaround adds days; plan accordingly.

Tools You'll Use​

Visual Studio Code (VS Code)​

Your primary text editor for writing MDX files.

Key features:

  • Syntax highlighting for Markdown and JSX
  • Built-in terminal for running commands
  • Extensions for improved MDX support
  • Git integration

Command Line / Terminal​

Used to run npm commands like npm start and npm build.

Don't worry! You only need to know a handful of commands (all covered in this guide).

Node.js & npm​

  • Node.js - JavaScript runtime that powers Docusaurus
  • npm - Package manager that installs project dependencies

What you need to know: Run npm install once during setup, then use npm start to run the site locally.

Git & GitHub Desktop​

  • Git - Tracks changes to your files
  • GitHub Desktop - User-friendly interface for Git (no command line needed)

What you need to know: Use GitHub Desktop to commit changes and sync with the repository.

Getting Help​

Within This Guide​

  • Troubleshooting & FAQ - Solutions to common problems
  • Search - Use the search bar (top right) to find specific topics

External Resources​

Contact​

If you encounter issues not covered in this guide:

  • Contact the repository administrator, Adam Gohs
  • Create an issue in the GitHub repository

Documentation Philosophy​

Good documentation should be:

✅ Clear - Easy to understand for the intended audience
✅ Accurate - Technically correct and up to date
✅ Complete - Covers all necessary topics without gaps
✅ Consistent - Follows established conventions and style
✅ Accessible - Usable by people with disabilities
✅ Maintainable - Easy to update and extend

This guide helps you create documentation that meets these standards.

Ready to Begin?​

Start with Getting Started to set up your development environment.

Once you're set up, proceed through the guide sequentially or jump to specific topics using the sidebar.

Welcome to the team! We're excited to have you contributing to the RMC Software Documentation project.

Document Information​

Guide Version: 2.0
Last Updated: February 2026
Maintained By: RMC Software Documentation Team

Note

This documentation guide is itself built using Docusaurus and MDX! As you read through this guide, you're seeing examples of what you'll learn to create.

Last updated on