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.
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
| # | Tool | Job | What it catches or produces |
|---|---|---|---|
| 1 | Vale | Prose lint | Style guide violations, banned terms, passive voice rules |
| 2 | markdownlint-cli2 | Markdown lint | Broken heading order, inconsistent lists, bare URLs |
| 3 | CSpell | Spelling | Typos in docs and code comments, with tech dictionaries |
| 4 | lychee | Link check | Dead external and internal links |
| 5 | pre-commit | Hook runner | Runs doc checks before each commit |
| 6 | terraform-docs | Generator | Inputs, outputs and providers tables for Terraform modules |
| 7 | helm-docs | Generator | Values tables for Helm charts |
| 8 | Spectral | API lint | OpenAPI files missing descriptions, examples or naming rules |
| 9 | Redocly CLI | API docs | Validates OpenAPI and builds HTML reference docs |
| 10 | Mermaid | Diagrams as code | Flowcharts and sequence diagrams rendered from text |
| 11 | Structurizr | Architecture | C4 model diagrams from one source |
| 12 | adr-tools | Decision records | Numbered architecture decision records in the repo |
| 13 | MkDocs (strict mode) | Build check | Fails the build on broken internal references |
| 14 | git-cliff | Changelog | Changelogs 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
| Check | Pre-commit | Pull request | Scheduled |
|---|---|---|---|
| markdownlint, CSpell | Yes | Yes | No |
| Vale | Optional (can be slow on big repos) | Yes | No |
| lychee, internal links | No | Yes | Optional |
| lychee, external links | No | Optional (sites flake) | Weekly |
| terraform-docs and helm-docs drift | Yes (regenerate) | Yes (fail on diff) | No |
| Spectral, Redocly lint | Optional | Yes | No |
| mkdocs build --strict | No | Yes | No |
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
| Mistake | What happens | Better approach |
|---|---|---|
| Turning on every Vale rule at once | Hundreds of warnings; people ignore all of them | Start with a handful of rules and add more over time |
| Hand-editing generated sections | The next regeneration wipes the edit | Put prose outside the BEGIN_TF_DOCS and END_TF_DOCS markers |
| Running checks only in CI | Slow feedback and noisy pull requests | Run the fast checks through pre-commit as well |
| Failing builds on flaky external links | Unrelated pull requests go red | Exclude known-flaky domains, schedule external checks |
| Diagrams kept as image files only | Nobody updates them after the first version | Keep 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 pain | Start with |
|---|---|
| Docs full of dead links | lychee on a weekly schedule |
| Module READMEs out of date | terraform-docs or helm-docs with a drift check |
| Inconsistent tone and terms | Vale with a small custom style |
| API docs do not match the API | Spectral plus Redocly CLI from the same spec |
| Nobody knows why systems look the way they do | adr-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
0
Dislike
0
Love
0
Funny
0
Angry
0
Sad
0
Wow
0