Glossary
Documentation validation
Definition
Documentation validation is the practice of checking the claims documentation makes against the software it describes — its source code, a specification or a running deployment — and recording each claim that does not hold as a finding to fix.
Validation is not review
Review and validation are both done to documentation before it ships, and they catch different failures.
Review is a person reading a page and asking whether it is clear, complete and well organized. Validation asks whether it is true. A reviewer can approve a beautifully written page whose example fails on the first line, because nothing in reading it reveals that the parameter was renamed last month.
Both matter. Only one of them can be done without the software in front of you, and it is not validation.
What documentation is validated against
A claim is only as checkable as the thing you compare it to. There are two references, and they catch different errors:
- The code. Names, signatures, types, defaults and configuration keys can be compared directly with the source. This catches a parameter that no longer exists or a default that changed.
- A running system. Commands, API calls and response shapes have to be exercised to know whether they behave as written. That is runtime validation, and it catches what reading the code cannot: the route that returns 404, the flag the CLI rejects.
Validating against only one leaves a class of errors unchecked.
What a validation produces
The useful output is a list of findings, not a score. Each finding names the claim, where it appears, and what was actually observed. A list like that is a work queue: someone can pick up the first item and fix it.
A single percentage is easier to report and harder to act on. It tells you something is wrong without telling anyone what.
When to validate
Once to establish a baseline, then on every release. Documentation that was validated last quarter describes code that has since changed, and every release is a fresh chance for a claim to stop holding. A one-time audit finds today's errors; a recurring check is what keeps the number near zero.
Go deeper
Questions people ask
Is documentation validation the same as linting docs?
No. A docs linter checks style, spelling, broken links and markup. It can pass a page whose every example is wrong. Validation checks the content against the software.
Do AI-generated docs still need validation?
Yes. Generating a page and checking it are separate steps. A model writes fluent, plausible text whether or not it is correct, so generated documentation needs validating as much as hand-written documentation does.
What should we do with the findings?
Fix them in the order readers reach them — getting started and authentication first — then re-run the check to confirm the fixes held.