Testing your Documentation¶
|last-updated:||February 13, 2017|
Testing your documentation allows you to make sure it is in a consistent state. Doing this gives your users a better experience, and reduces stress around common issues as a writer.
This article by Anne Gentle is a good place to start to understand this concept.
The most useful tests are run on each commit of your project. This is called Continuous Integration, and is a common practice in the software development world.
We recommend checking out the following tools to get started:
The easiest automated check to do is to make sure your documentation builds properly. This requires simply running your documentation tool, and checking that it has properly built your documentation.
Most tools will return an error code of 0 if the process is successful. This means you should just be able to do a normal build of your tool, and your testing tool will know if it is successful or not.
If your build tool has a picky mode that flags warnings that might be problematic as well as errors, it might make sense to switch it on, but you’ll want to make sure that your documentation is in good shape before you do.
Style Guide Checking and Linting¶
Linters are tools that automatically verify specific rules against your code or documentation. This is useful for enforcing a style guide,or for catching commonly mitaken branding issues.
Here are a few links that might be interesting:
“Naive linter for English prose for developers who can’t write good and wanna learn to do other stuff good too.”
This linter is a prose linter for English. It has a number of checks for things like:
- Passive voice
- Lexical illusions
- Weasel words