Testing Your Documentation: Tools and Techniques for Docs Quality
Software teams would never ship code without tests, yet most ship documentation with no automated checks at all. The result is predictable: dead links, code samples that no longer compile, inconsistent terminology, and typos that slip past tired eyes. These are exactly the kinds of errors machines catch reliably and humans catch inconsistently. Treating documentation as testable — running automated quality checks on every change, the same way you test code — is one of the highest-leverage practices a documentation team can adopt.
The good news is that a mature ecosystem of documentation-testing tools already exists, most of it free and open source, and most of it slots directly into a docs-as-code pipeline. This article walks through the specific technical writing tools that catch errors automatically and how to wire them into continuous integration so bad content never reaches a reader.
Why Documentation Needs Testing
Documentation errors cost trust and support time. A broken link tells a reader the docs are neglected; a code sample that fails to run tells a developer the whole reference might be unreliable; inconsistent terminology makes readers wonder whether two terms mean different things. These failures accumulate silently between releases and are tedious to catch by hand across hundreds of pages. Automated testing solves the scale problem: a link checker validates thousands of links in seconds, a linter enforces terminology consistently across every file, and a code-sample test proves your examples still work against the current API. The shift in mindset is to treat every documentation error class as something a machine can guard, reserving human review for the judgment calls — clarity, accuracy of meaning, and whether the content actually helps. This is the same discipline that keeps large doc sets maintainable as they scale.
Prose Linting With Vale
Vale is the standard prose linter for technical documentation and the single most valuable tool in this category. It checks your writing against configurable rules: banned or preferred terms, spelling of product names, passive voice, sentence length, heading capitalisation, and much more. Crucially, Google, Microsoft, and the Write the Docs community all publish ready-made Vale rule sets for their style guides, so you can enforce an established standard with minimal configuration and add your own terminology on top. Vale runs in the writer's editor for instant feedback and in CI to block non-compliant content from merging. This turns your style guide from a document people are meant to remember into automated checks, applied consistently and without the friction of a reviewer pointing out the same terminology slip for the hundredth time. The Vale documentation covers setup and rule authoring in detail.
Link Checking and Spell Checking
Broken links are the most common and most trust-eroding documentation defect, and they are trivial to catch automatically. Tools like lychee, htmltest, or markdown-link-check crawl your content and report every dead internal and external link. Run them in CI so a link that breaks — whether because a page moved or an external site changed — fails the build before publication. Schedule a periodic full crawl too, since external links rot over time even when your content does not change. For spelling, tools like codespell or cspell catch typos while respecting a custom dictionary of your product's technical terms, so you are not drowning in false positives on legitimate jargon. These checks are cheap to add and eliminate whole categories of embarrassing, credibility-damaging errors that human proofreading catches only unreliably at scale.
Testing Code Samples
Code samples that do not work are worse than no samples, because a developer wastes time debugging your error before concluding the docs are untrustworthy. The strongest technique is to make your examples executable and test them. Python's doctest runs code embedded in documentation and checks its output. For other languages, extract samples into a test suite that compiles and runs them against the current API in CI, so any change that breaks an example fails the build. Where full execution is impractical, at least lint and compile samples so syntax errors cannot ship. Generating examples from your source or SDKs, rather than hand-maintaining them, is another form of this discipline — the sample cannot drift from reality if it is produced from reality. Testing code samples is what separates reference documentation developers trust from reference documentation they learn to distrust, a point we expand on for API references specifically.
Wiring It All Into CI
Individual tools help, but the payoff comes from running them automatically on every change. In a docs-as-code setup, add these checks to your continuous integration pipeline — GitHub Actions, GitLab CI, or similar — so every pull request runs the linter, link checker, spell checker, code-sample tests, and a build validation before it can merge. A failed check blocks the merge, which means bad content is caught at authoring time by the person who can most easily fix it, not discovered later by a reader. Add a preview deployment per PR so reviewers see the rendered result. This CI gate is the mechanism that makes documentation quality a property of the process rather than a matter of individual diligence, which is essential once more than one person contributes.
What Automation Can't Test
Automation catches mechanical errors, but it cannot judge whether documentation is actually good. It cannot tell you if an explanation is clear, if the structure matches how readers think, if an example is realistic, or if the content answers the question a reader actually has. Those require human review and real user feedback — usability testing, support-ticket analysis, and "was this helpful?" signals. The right model is a division of labour: let machines guard everything mechanical so human attention concentrates entirely on meaning, clarity, and usefulness. To build a complete documentation-testing pipeline and the review practices around it, Darlo's Documentation Tooling & QA course walks through setting up Vale, link checking, and CI from scratch, and our free Docs QA Pipeline Checklist template lists every automated check worth adding, in priority order. Explore both at /courses.
Docs QA Pipeline Checklist
A prioritized list of every automated documentation check worth adding — prose linting, link and spell checking, code-sample tests, and CI gates — with the tool to use for each and how to wire it in.
What is the best tool for enforcing a documentation style guide?
Vale, the open-source prose linter. It checks writing against configurable rules for terminology, voice, and formatting, and Google, Microsoft, and Write the Docs publish ready-made rule sets. It runs in the editor for instant feedback and in CI to block non-compliant content.
How do you keep code samples in documentation from breaking?
Make them executable and test them in CI. Use tools like Python's doctest, or extract samples into a test suite that compiles and runs them against the current API. Better still, generate samples from your source or SDKs so they cannot drift from reality.
Can documentation quality be fully automated?
No. Automation reliably catches mechanical errors — broken links, typos, terminology, failing samples — but it cannot judge clarity, structure, or whether content answers the reader's real question. Use machines for the mechanical, and human review plus user feedback for meaning and usefulness.