14 Tools That Improve DevOps Documentation

14 open-source tools that keep DevOps docs accurate: Vale, markdownlint, lychee, terraform-docs, helm-docs, Spectral, Mermaid and more, with CI commands.

Dec 23, 2025 - 16:03
Nov 9, 2026 - 03:27
 0  76
14 Tools That Improve DevOps Documentation

The tools that improve DevOps documentation most are the ones that check and generate it automatically: linters such as Vale and markdownlint, link checkers such as lychee, generators such as terraform-docs and helm-docs, API linters such as Spectral, and diagram-as-code tools such as Mermaid. Run them in CI so stale or broken docs fail the build.

Our sibling post on documentation tools for knowledge sharing covers where docs should live (portals, wikis, static sites). This post covers the next problem: keeping those docs accurate. Every tool below can run in a pipeline, and each comes with a command you can try today.

Key takeaways

  • Documentation decays because nobody is told when it breaks. Automated checks fix that.
  • Group tools by job: write well (lint), stay correct (links, generated reference), explain structure (diagrams, decisions), and publish safely.
  • Generated docs, such as Terraform module inputs or Helm values, should never be edited by hand. Regenerate and check for drift in CI.
  • Start with three tools: markdownlint, a link checker and one generator for your main stack.
  • All 14 tools here are open source and run from the command line.

The 14 tools at a glance

#ToolJobWhat it catches or produces
1ValeProse lintStyle guide violations, banned terms, passive voice rules
2markdownlint-cli2Markdown lintBroken heading order, inconsistent lists, bare URLs
3CSpellSpellingTypos in docs and code comments, with tech dictionaries
4lycheeLink checkDead external and internal links
5pre-commitHook runnerRuns doc checks before each commit
6terraform-docsGeneratorInputs, outputs and providers tables for Terraform modules
7helm-docsGeneratorValues tables for Helm charts
8SpectralAPI lintOpenAPI files missing descriptions, examples or naming rules
9Redocly CLIAPI docsValidates OpenAPI and builds HTML reference docs
10MermaidDiagrams as codeFlowcharts and sequence diagrams rendered from text
11StructurizrArchitectureC4 model diagrams from one source
12adr-toolsDecision recordsNumbered architecture decision records in the repo
13MkDocs (strict mode)Build checkFails the build on broken internal references
14git-cliffChangelogChangelogs generated from conventional commits

Write well: lint prose and Markdown

1. Vale

Vale is a prose linter that applies style rules written in YAML. You can use published styles (Microsoft, Google, write-good) or write your own, for example to enforce "Kubernetes" over "k8s" in user-facing docs.

# .vale.ini
StylesPath = .github/styles
MinAlertLevel = suggestion
Packages = Microsoft

[*.md]
BasedOnStyles = Vale, Microsoft
vale sync      # download the packages listed above
vale docs/

2. markdownlint-cli2

markdownlint-cli2 checks Markdown against the markdownlint rule set (heading levels, list style, line length). Consistent source makes reviews easier and renders reliably across tools.

npx markdownlint-cli2 "docs/**/*.md" "#node_modules"

3. CSpell

CSpell spell-checks text and code, and ships dictionaries for software terms. Add project words to cspell.json so names like your service names stop triggering noise.

npx cspell "docs/**/*.md"

Stay correct: links, hooks and generated reference

4. lychee

lychee is a fast link checker written in Rust. It reads Markdown, HTML and plain text and reports dead links. Run it on pull requests and on a weekly schedule, because external pages break without any change in your repo.

lychee --no-progress "docs/**/*.md"

5. pre-commit

pre-commit manages Git hooks from a single YAML file, so every contributor runs the same checks locally. It keeps doc problems out of pull requests in the first place.

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/DavidAnson/markdownlint-cli2
    rev: v0.13.0
    hooks:
      - id: markdownlint-cli2
  - repo: https://github.com/terraform-docs/terraform-docs
    rev: v0.19.0
    hooks:
      - id: terraform-docs-go
        args: ["markdown", "table", "--output-file", "README.md", "./modules/vpc"]

Pin rev to the current release tags in each project; the versions above are examples.

6. terraform-docs

terraform-docs reads a module's variables and outputs and writes them as a Markdown table. Use inject mode so it updates only the section between markers in your README.

terraform-docs markdown table --output-file README.md --output-mode inject ./modules/vpc

In CI, regenerate and fail if git diff --exit-code shows a change. That proves the README matches the code. Our Terraform production practices post covers module structure.

7. helm-docs

helm-docs generates a values table for each chart from values.yaml and comments that start with # --.

# values.yaml
# -- Number of replicas for the web Deployment
replicaCount: 2
helm-docs --chart-search-root charts/

Document APIs from the spec

8. Spectral

Spectral lints OpenAPI and AsyncAPI files against rule sets. The built-in spectral:oas rules catch missing operation descriptions and invalid examples; you can add rules such as "every endpoint needs a tag".

echo 'extends: ["spectral:oas"]' > .spectral.yaml
npx @stoplight/spectral-cli lint openapi.yaml

9. Redocly CLI

Redocly CLI validates OpenAPI definitions and builds a standalone HTML reference page, so API docs come straight from the spec that the code uses.

npx @redocly/cli lint openapi.yaml
npx @redocly/cli build-docs openapi.yaml -o api.html

For testing the APIs themselves, see API testing tools for DevOps teams.

Explain structure: diagrams and decisions

10. Mermaid

Mermaid renders diagrams from text. GitHub, GitLab and many static site generators render Mermaid code blocks in Markdown, so diagrams are reviewed in pull requests like code.

```mermaid
flowchart LR
  Dev[Developer] --> PR[Pull request] --> CI[CI checks] --> Prod[Production]
```

11. Structurizr

Structurizr builds C4 model diagrams (context, container, component) from a single DSL file. Because many views come from one model, a renamed service changes everywhere at once.

workspace {
  model {
    user = person "Customer"
    shop = softwareSystem "Shop" {
      api = container "Orders API"
    }
    user -> api "Places orders"
  }
  views {
    container shop { include * }
  }
}

12. adr-tools

Architecture decision records capture why a choice was made. adr-tools creates numbered Markdown files and links superseded decisions.

adr init docs/adr
adr new "Use Argo CD for production deployments"

Publish safely and record changes

13. MkDocs in strict mode

Running mkdocs build --strict turns warnings, such as links to missing pages, into a failed build. It is a cheap final check before publishing.

mkdocs build --strict

14. git-cliff

git-cliff generates a changelog from Git history, grouped by conventional commit types such as feat and fix. Release notes then match what actually merged.

git cliff -o CHANGELOG.md

Putting it together in one CI job

name: docs
on: [pull_request]
jobs:
  docs-quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: DavidAnson/markdownlint-cli2-action@v25
        with:
          globs: "docs/**/*.md"
      - uses: lycheeverse/lychee-action@v2
        with:
          args: --no-progress "docs/**/*.md"
      - name: Terraform docs drift
        run: |
          docker run --rm -v "$PWD:/w" -w /w quay.io/terraform-docs/terraform-docs:latest \
            markdown table --output-file README.md --output-mode inject ./modules/vpc
          git diff --exit-code

Check each action's README for the current major version before you copy this.

Writing your first custom Vale rule

Published styles catch general problems. The rules that pay off fastest are the ones that encode your own team's terms. Vale's substitution rule type swaps one term for another and reports each hit:

# .github/styles/Team/Terms.yml
extends: substitution
message: "Use '%s' instead of '%s'."
level: error
ignorecase: true
swap:
  k8s: Kubernetes
  master branch: main branch
  whitelist: allowlist
  blacklist: denylist

Add Team to BasedOnStyles in .vale.ini. Start with level: warning for a few weeks so writers can see the rule before it blocks merges, then raise it to error.

Where each check should run

CheckPre-commitPull requestScheduled
markdownlint, CSpellYesYesNo
ValeOptional (can be slow on big repos)YesNo
lychee, internal linksNoYesOptional
lychee, external linksNoOptional (sites flake)Weekly
terraform-docs and helm-docs driftYes (regenerate)Yes (fail on diff)No
Spectral, Redocly lintOptionalYesNo
mkdocs build --strictNoYesNo

External link checks belong on a schedule because remote sites go down for reasons unrelated to the pull request. A weekly job that opens an issue is less annoying than a red build on an unrelated change.

Common mistakes when adding doc checks

MistakeWhat happensBetter approach
Turning on every Vale rule at onceHundreds of warnings; people ignore all of themStart with a handful of rules and add more over time
Hand-editing generated sectionsThe next regeneration wipes the editPut prose outside the BEGIN_TF_DOCS and END_TF_DOCS markers
Running checks only in CISlow feedback and noisy pull requestsRun the fast checks through pre-commit as well
Failing builds on flaky external linksUnrelated pull requests go redExclude known-flaky domains, schedule external checks
Diagrams kept as image files onlyNobody updates them after the first versionKeep the Mermaid or Structurizr source in the repo

How to tell if documentation is improving

  • Count of broken links reported by the weekly lychee job, tracked over time.
  • Number of modules and charts whose generated docs pass the drift check.
  • Share of pull requests that change code and docs together in the same commit range.
  • Age of the oldest runbook or ADR that has not been reviewed.
  • Questions in team chat that are answered with a link to existing docs.

None of these need a new tool. They come from CI results and repository history you already have.

Which tools to start with

Your main painStart with
Docs full of dead linkslychee on a weekly schedule
Module READMEs out of dateterraform-docs or helm-docs with a drift check
Inconsistent tone and termsVale with a small custom style
API docs do not match the APISpectral plus Redocly CLI from the same spec
Nobody knows why systems look the way they doadr-tools and Structurizr

Docs-as-code habits are part of Git and pipeline work, which we cover in Git repository management practices and in our DevOps training in Pune (Kharadi classroom and live online).

Frequently asked questions

What tools improve DevOps documentation?

Tools that check and generate docs automatically: Vale and markdownlint for writing, lychee for links, terraform-docs and helm-docs for generated reference, Spectral and Redocly for APIs, and Mermaid or Structurizr for diagrams.

How is this list different from documentation platforms?

Platforms such as wikis, Backstage TechDocs or Docusaurus host docs. The tools here keep those docs accurate. Our post on documentation tools for knowledge sharing covers platforms.

What is docs as code?

Writing docs in plain text next to the code, reviewing them in pull requests and testing them in CI, the same way you treat source code.

How do I stop Terraform READMEs going stale?

Generate them with terraform-docs and add a CI step that regenerates and runs git diff --exit-code. Any drift fails the pull request.

Can diagrams be version controlled?

Yes. Mermaid and Structurizr diagrams are text files, so changes show up in diffs and go through review.

Which documentation check should I add first?

A link checker. Dead links are the most common and visible doc defect, and lychee needs almost no setup.

What is an architecture decision record?

A short document that records a technical decision, its context and its consequences. Tools like adr-tools keep them numbered in the repository.

References

What's Your Reaction?

Like Like 0
Dislike Dislike 0
Love Love 0
Funny Funny 0
Angry Angry 0
Sad Sad 0
Wow Wow 0
Mridul I am a passionate technology enthusiast with a strong focus on DevOps, Cloud Computing, and Cybersecurity. Through my blogs at DevOps Training Institute, I aim to simplify complex concepts and share practical insights for learners and professionals. My goal is to empower readers with knowledge, hands-on tips, and industry best practices to stay ahead in the ever-evolving world of DevOps.