Documentation as Code

Treating Docs Like Software

The docs-as-code approach applies software development practices -- version control, code review, continuous integration, automated testing -- to documentation. Instead of documentation living in a disconnected wiki that rots quietly, it lives alongside the code it describes, goes through the same review process, and is deployed through the same pipeline. For QA teams, this approach is particularly powerful because test documentation, test reports, and quality metrics can be generated, validated, and published automatically.

Why Docs-as-Code

Traditional documentation tools (Google Docs, Confluence, SharePoint) have a fundamental problem: they are disconnected from the codebase. When the code changes, the documentation does not automatically update. Nobody notices when a wiki page becomes inaccurate. There is no review process to catch errors. There is no version history that correlates with code changes.

Choosing the Right Format

Markdown

The most common format for docs-as-code. Simple, readable as plain text, widely supported.

Strengths:

• Nearly zero learning curve
• Readable without rendering
• Supported by GitHub, GitLab, Bitbucket, and most static site generators
• Great tooling ecosystem (linters, formatters, editors)

Weaknesses:

• Limited formatting options (no admonitions, tabs, or complex layouts without extensions)
• No native support for includes or content reuse
• Table syntax is cumbersome for complex tables

Best for: README files, test documentation, runbooks, API guides, most QA documentation.

AsciiDoc

A more powerful markup language with native support for complex document structures.

Strengths:

• Native admonitions (NOTE, TIP, WARNING, IMPORTANT)
• Includes (import content from other files)
• Table of contents generation
• Conditional content (show/hide based on variables)
• Cross-references between documents

Weaknesses:

• Steeper learning curve than Markdown
• Less tooling support than Markdown
• Not natively supported by GitHub rendering (rendered as basic text)

Best for: Comprehensive test strategy documents, standards documents, documentation that requires complex structure.

reStructuredText (rST)

The standard for Python documentation. Powerful but with the steepest learning curve.

Strengths:

• Native directives for complex content
• Excellent for API documentation (Sphinx integration)
• Strong cross-referencing
• Industry standard in Python ecosystem

Weaknesses:

• Unfamiliar syntax for most developers
• Less readable as plain text than Markdown
• Smaller community outside Python

Best for: Python-based test frameworks, projects that already use Sphinx.

Format Comparison

Recommendation for most QA teams: Start with Markdown. It has the lowest barrier to adoption. Switch to AsciiDoc or rST only if you hit limitations that Markdown extensions cannot solve.

Documentation Generators

Docusaurus

React-based static site generator from Meta. Excellent for project documentation with versioning.

MkDocs (with Material theme)

Python-based, simple, fast. The Material theme adds a polished UI with excellent search.

GitBook

Commercial platform with a clean UI. Good for teams that want a hosted solution.

Confluence

The most common enterprise wiki. Not strictly docs-as-code, but can be integrated.

Test Documentation in the Repo

Co-Locating Test Docs with Test Code

The most effective place for test documentation is next to the tests themselves.

Repository structure example:

project/
├── src/
│   ├── checkout/
│   │   ├── checkout.ts
│   │   └── checkout.test.ts
│   └── payment/
│       ├── payment.ts
│       └── payment.test.ts
├── tests/
│   ├── e2e/
│   │   ├── checkout.spec.ts
│   │   └── README.md          ← What these tests cover
│   ├── performance/
│   │   ├── load-test.js
│   │   └── README.md          ← How to run, thresholds, history
│   └── test-data/
│       ├── fixtures/
│       └── README.md          ← How test data works
├── docs/
│   ├── test-strategy.md       ← Overall test strategy
│   ├── test-environments.md   ← Environment setup guide
│   └── runbooks/
│       ├── deploy-verification.md
│       └── incident-response.md
└── README.md

Benefits of co-location:

• Developers see test documentation when they change test code
• Documentation changes are reviewed in the same PR as code changes
• Git blame shows who wrote the documentation and when
• Documentation is always version-matched with the code

What to Put in the Repo vs. External Wiki

Automating Documentation

Test Reports

Automated test reports generated by CI/CD pipelines provide up-to-date quality metrics without manual effort.

What to generate automatically:

Coverage Reports

Coverage reports can be generated and published automatically:

# Example GitHub Actions step
- name: Generate coverage report
  run: npx nyc report --reporter=html --reporter=text

- name: Publish coverage to GitHub Pages
  uses: peaceiris/actions-gh-pages@v3
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./coverage

Documentation Linting

Automated checks that keep documentation quality high:

Example CI configuration for documentation linting:

# .github/workflows/docs.yml
name: Documentation Quality
on: pull_request
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Lint Markdown
        uses: DavidAnson/markdownlint-cli2-action@v14
      - name: Check links
        uses: lycheeverse/lychee-action@v1
        with:
          args: --verbose docs/**/*.md
      - name: Spell check
        uses: streetsidesoftware/cspell-action@v5

Documentation Review Process

Who Reviews

When to Review

• On change: Every documentation change goes through a PR review, just like code
• On schedule: Quarterly review of all active documentation for accuracy and relevance
• On trigger: When a related incident occurs, review relevant runbooks and documentation

How to Review Documentation

Keeping Docs Fresh

Automated Staleness Detection

Set up systems that alert when documentation has not been updated in a defined period:

• Git-based: Script that checks the last commit date for each doc file and flags those older than 90 days
• Wiki-based: Confluence and Notion both support "last updated" tracking; some support automated reminders
• CI-based: Add a job that runs weekly and creates issues for stale documentation

Example staleness check script concept:

# Find documentation files not updated in 90 days
find docs/ -name "*.md" -mtime +90 -print

Ownership Model

Every document should have a designated owner. The owner is not necessarily the author -- they are the person responsible for keeping the document accurate.

Maintenance Schedules

Hands-On Exercise

1. Move one piece of test documentation from your wiki into your code repository. Set it up as a Markdown file in the appropriate location.
2. Add a documentation linting step to your CI pipeline (markdownlint, link checking, or spell checking).
3. Set up automated test report generation and publishing for your project.
4. Create a documentation ownership table for your team's key documents. Identify any orphaned documents.
5. Implement a staleness detection mechanism: either a script, a calendar reminder, or an automated check that flags documents older than 90 days.