I recently spoke at Write the Docs Prague 2015. A video will be published soon, but for now the slides are available with a rough transcript.
The topic was “Tested and Correct, How to Make Sure Your Documentation Keeps Working” and the abstract was
When you are writing documentation for software, a top priority is surely that what you write is correct. That is, the examples you provide give the output you say they will. Or perhaps it is that the links in your documentation link to an expected page. Usually this is done with manual testing at the time of writing. Your organisation may have practices in place to make sure that these examples don’t get too out of date – maybe someone checks them periodically, maybe code review comes with comments like “I remember that this part of the code is used in an example on Page 37 of our docs, change it”. But these methods are tedious and flawed. This talk will give examples from my work as a software engineer in creating tested snippets for documentation which are linked to the code they represent. It will show how using techniques traditionally reserved for software testing can ease the burden of keeping documentation up to date.
A rough transcript is here.
Technologies mentioned include:
- sphinx.builders.linkcheck.CheckExternalLinksBuilder for checking links
- sphinxcontrib.spelling for checking spelling
- TaskDirective from Flocker by ClusterHQ for checking command line instruction correctness
- wordish for basic shell instructions in reStructuredText
- selenium for automating web browsers