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

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. DOCX Converter - Convert Word documents to MDX format
  2. Creating and Editing Pages - Comprehensive MDX guide with Markdown and JSX syntax
  3. React Components - Complete component library reference

Reference Materials​

  1. Troubleshooting & FAQ - Solutions to common problems

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)

    • 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:

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

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="fig-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​

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

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, administrator coordination, testing procedures, and complete examples.

High-Level Steps:

  1. Determine folder location based on hierarchy (see Complete Walkthrough)
  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

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 minor edits (typos, small clarifications):

  1. Edit the existing version's MDX files directly
  2. Test locally
  3. Commit changes

For major updates (new features, substantial changes):

  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

Typical time: 30 minutes to 2 hours depending on scope

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: January 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