Tested and Correct, How to Make Sure Your Documentation Keeps Working

Description

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.

  • Conference: Write the Docs EU
  • Year: 2015

About the speaker

Adam Dangoor