Docs as Code

Documentation belongs in the development workflow.

DocOps treats documentation like software: it lives in version control, goes through review, can be tested, and is built and published through the same workflow used for the application.

Overview

Docs as code means using software development practices to manage documentation.

Instead of keeping documentation in a separate content management system, the source files live in the repository with the code and tools used to build and publish them.

This makes it easier to review changes, catch problems, automate repetitive work, and see what changed over time.

A docs-as-code system typically includes:

• Version control for documentation source.
• Peer review through pull requests.
• Automated checks before changes are published.
• Repeatable builds for local development and production.
• CI/CD for building and deploying documentation.
• Change history that shows what changed, when, and why.

Architecture

DocOps keeps content, presentation, validation, and publishing in the same version-controlled system.

Documentation source
        ↓
       Git
        ↓
   Pull request
        ↓
  Automated checks
        ↓
      Build
        ↓
     Deploy
        ↓
Published documentation

The DocOps application uses Next.js and MDX for documentation and React components.

SCSS handles the presentation separately from the documentation content.

Repository

The repository should make it easy to understand how the documentation works.

DocOps keeps application routes, reusable components, styles, documentation assets, and automation in separate areas:

docops/
├── .github/
│   └── workflows/
├── docs/
│   └── assets/
├── src/
│   ├── app/
│   ├── components/
│   └── styles/
├── mdx-components.tsx
├── next.config.ts
└── package.json

Local development

Contributors should be able to run the documentation site on their own machine.

Install the project dependencies:

npm install

Start the local development server:

just run

This makes it easy to see changes before they are submitted for review.

A production build can also be tested locally:

npm run build

Git workflow

Documentation changes follow the same basic workflow as code changes.

1. Create or update the documentation.
2. Review the change locally.
3. Run the required checks.
4. Commit the change with a meaningful message.
5. Push the change to the remote repository.
6. Review and merge the change.

Small, focused commits make it easier to understand the history and review individual changes.

Validation

Documentation should not depend entirely on someone manually checking every change.

A documentation pipeline can check for:

• application build errors
• broken links
• style problems
• missing metadata
• OpenAPI problems
• code example errors
• accessibility issues
• stale content

DocOps will turn these checks into actual tools over time instead of treating them as a list of recommendations.

Publishing

Publishing should be part of the same workflow as writing and reviewing documentation.

Once a change has been reviewed and the required checks pass, the documentation can be built and published through the project's deployment process.

Keeping publishing connected to the repository makes the process repeatable and gives the team a clear history of what was published and when.

The system described by DocOps is also the system used to build DocOps.