Docs as code

A documentation workflow built for safe, frequent change.

This workflow blueprint connects writing, technical review, automated checks, previews, and release ownership.

Source: Git repository
Review: Pull request
Release: Automated

Repository architecture

Organize source by reader purpose.

Content types remain distinct, validation scripts stay versioned beside the content they protect, and ownership rules are visible in the repository.

Concepts explain systems and mental models.
Guides help readers complete bounded tasks.
Reference defines exact interfaces and behavior.
Troubleshooting starts with observable symptoms.

Repository treetext

docs/
├── concepts/
├── guides/
├── reference/
└── troubleshooting/
scripts/
├── check-links.mjs
└── validate-examples.mjs
.github/
├── CODEOWNERS
└── workflows/docs.yml
vale.ini

Delivery workflow

Every change passes the same six gates.

01Scope
Define the reader, task, source of truth, acceptance criteria, owner, and release dependency.
02Draft
Write in a branch with locally validated examples and explicit assumptions for reviewer attention.
03Validate
Run structure, style, link, schema, code-example, accessibility, and build checks.
04Review
Route technical claims to subject-matter owners and user experience to documentation reviewers.
05Preview
Inspect the rendered site, navigation, code wrapping, responsive layout, metadata, and changed links.
06Release
Publish from the reviewed commit, verify production, and retain a direct rollback path.

Automated validation

Catch checkable errors before publication.

This workflow template grants read-only repository access, installs locked dependencies, and invokes your documentation checks. Define the named npm scripts in your repository. Automated checks support technical review; they do not establish that every explanation is correct.

Content checks

Required frontmatter, heading order, terminology, inclusive language, and stale review dates.

Technical checks

Internal links, OpenAPI validity, command syntax, executable examples, and generated reference drift.

Rendered checks

Build output, canonical URLs, structured data, accessibility rules, and security headers.

.github/workflows/docs.ymlyaml

name: Validate documentation

on:
  pull_request:
    paths:
      - "docs/**"
      - "scripts/**"
      - ".github/workflows/docs.yml"
      - ".github/CODEOWNERS"
      - "package.json"
      - "package-lock.json"
      - "vale.ini"

permissions:
  contents: read

jobs:
  validate:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run lint:docs
      - run: npm run check:links
      - run: npm run test:examples
      - run: npm run build:docs

Review ownership

Ask the right reviewer for the right decision.

A technical writer owns clarity and completeness. Product and engineering owners verify behavior. Support contributes recurring failure patterns.

Replace the example handles with valid users or organization teams that have write access. Configure branch protection or a ruleset to require code-owner approval; a CODEOWNERS file alone does not enforce approval. When a line lists several owners, approval from one can satisfy the code-owner requirement. See GitHub’s code-owner rules.

.github/CODEOWNERStext

# Product documentation
/docs/concepts/         @product-docs @product
/docs/guides/           @product-docs @developer-experience
/docs/reference/        @product-docs @api-engineering
/docs/troubleshooting/  @product-docs @support-engineering

# Quality controls
/scripts/               @developer-experience
/.github/workflows/     @platform-engineering

Release control

A successful build is not the final check.

01
Bind the artifact to a commit
The deployed documentation must identify the exact source revision used to build it.
02
Verify production routes
Check changed pages, navigation, canonical URLs, assets, redirects, feeds, and the sitemap.
03
Notify discovery systems
Update the sitemap and notify supported search systems only after the production revision is live.
04
Keep rollback direct
Redeploy the previous known-good artifact without rebuilding source or changing unrelated content.

Release criterion

A documentation change is complete when the intended page is correct in production, its routes and metadata are valid, and its accountable owner can maintain it.

Related guidance

Read the implementation guide.

The long-form guide covers tooling choices, migration sequencing, contribution experience, and maintenance practices.

Read the docs-as-code guide Return to portfolio

Start a conversation

Need a maintainable documentation workflow?

Tell us how your team writes, reviews, and publishes documentation today.

Book a discovery call Send project details

Expect a reply within one business day.