# Documentation is validated in CI

- **Pattern:** `ab-001014` (`developer-documentation.maintenance.docs-ci`)
- **Severity:** info
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-001014
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-001014)

## Why it matters

Documentation that isn't validated in CI can rot silently: links break, code examples go stale, and the docs site fails to build — all without anyone noticing until a user reports it. iso-25010:2011 reliability.maintainability measures exactly this: a project where documentation quality is not continuously verified is a project where documentation quality will degrade over time. For vibe-coded projects that ship quickly and update frequently, undiscovered documentation rot is the rule, not the exception. A single markdown-link-check step in CI catches broken links before they reach users.

## Severity rationale

Info because broken documentation validation doesn't affect runtime behavior, but it signals a maintenance posture that allows documentation quality to degrade silently across all future changes.

## Remediation

Add a docs validation job to your CI pipeline. A minimal GitHub Actions workflow:

```yaml
# .github/workflows/docs.yml
name: Docs
on: [push, pull_request]
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run docs:build
      - run: npx markdown-link-check README.md docs/**/*.md
```

At minimum, validate that the docs site builds and that links in README.md resolve. Add `npx markdown-link-check` for link validation and a docs build step if the project has a generated docs site. Broken CI docs checks should block merge, not just warn.

## Detection

- **ID:** `docs-ci`
- **Severity:** `info`
- **What to look for:** Check CI configuration (.github/workflows/, .gitlab-ci.yml, etc.) for documentation-related steps: building the docs site, running link checkers (markdown-link-check, lychee, htmltest), checking for broken code examples (mdx compilation), or spell checking. This is a maintenance hygiene signal -- projects that validate docs in CI catch broken links and stale examples before they reach users. Count all instances found and enumerate each.
- **Pass criteria:** CI pipeline includes at least one documentation validation step: docs build, link checking, or code example validation. At least 1 implementation must be confirmed.
- **Fail criteria:** CI pipeline has no documentation-related steps. Docs can break without anyone noticing until a user reports it.
- **Skip (N/A) when:** The project has no CI pipeline configured at all (separate concern from documentation).
- **Detail on fail:** Example: `"GitHub Actions workflow has lint and test steps but no documentation validation"` or `"Docs site build is not in CI -- broken docs pages are only caught in production"`
- **Remediation:** Add a docs validation step to your CI:

  ```yaml
  # .github/workflows/docs.yml
  name: Docs
  on: [push, pull_request]
  jobs:
    docs:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v4
        - uses: actions/setup-node@v4
          with:
            node-version: 20
        - run: npm ci
        - run: npm run docs:build  # Verify docs compile
        - run: npx markdown-link-check README.md docs/**/*.md  # Check links
  ```

---

## External references

- iso-25010 reliability.maintainability

Taxons: operational-readiness

HTML version: https://auditbuffet.com/patterns/ab-001014