I’m at Write the Docs today in Budapest and will be posting notes from sessions throughout the day. These are all posted right after a talk finishes so they’re rough around the edges.
Kristof, who helped make this conference happen, is an evangelist in the Drupal community. His talk focused on documentation in a post-agile world. Given the more hectic nature of agile software development ensuring that your documentation is up to date is quite difficult. You end up maintaining multiple versions of documents, sometimes writing docs for features which haven’t yet shipped or even been finished in code. You know the docs will fail at some point, the question is when.
The trick, though, is that developers already solved these complexities in the shift to agile development. On the software side developers have automated aspects of QA in order to speed up deployment. Kristof believes we can take that same mindset to docs. You can do this by either merging docs in to tests or embedding tests in to docs. Both are difficult.
In DITA documentation is broken up in to references, tasks, and concepts. References are written in code or extracted from from code. Common examples are documentation around API functions; these become easy to test. Tasks let you document automated execution in your project. Concepts let you address places where terminology may change between two versions of your code. Using embedded RDFa or a thesaurus extractor you could try and ensure your code and documentation agree.
Kristof also talked a bit about building the ultimate user guide to the internet. This stems from his project WalkHub. The concept is that online tools and sites often require us to absorb too much information. Luckily, though, there is a shortcut; it’s about cognitive load reduction. People have a limited amount of working memory and if you dump too much information on them they’ll overload.