Keeping knowledge about a product alive is no easy task. Software teams struggle with manually mainting vast documentation in UML tools, text documents, wiki sites and more. We all know about the amount of effort and dedication needed to do this well given the amount of redundancy. There is a promising vision of a living documentation, i.e. a documentaiton automagically created from those things the teams create anyway, like automated and manual tests, backlog items, meeting protocols and more.

We have been leading a fascinating conversation about the topic living documentation in a topic team. The resulting sketch could serve as a vision of such a living documentation.

(1) Completely in line with the overarching topic of this blog, the stars to road framework, you might manage your innovation portfolio and this could be an entry point into the living documentation. Just click on an item to drill down.

(2) Once a item is in development. The team creates more artifacts, e.g. a user story map. A team might also want to link important documentation, like an inception deck, sketches for concepts and software architecture, the relevant personas or the results from user research. Again you can drill deeper by clicking on an item. There is obviously more information, if the item has already been worked on.

(3) In this example, the feature is maintain cart. The details are grabbed from an issue tracker, from test classes, manual tests, gherkin feature files and more. Automated tests appear with a name derived from the name in the code, the tickets in the issue tracker are directly linked. Thus items can be marked as being done and if a test fails, this can be shown as well.

(4) Of course, one could drill down into the test one step further. In case of a UI test, it could show you more precisely, what went wrong.

When clicking on a BDD test, the feature file with all the scenarios can be shown. An excellent way of documenting a business rule. It shows very accurately, what is implemented and which special cases are tested.

These conceptual sketches only give a hint of such a living documentation. The scenarioo team is currently working at enhancing their awesome living documentation tool to include additional tests (currently UI tests) as well as manually edited mark down files into their generated documentation. Looks very promising.

Hope to see something like this fairly soon so I don’t waste my time keeping documentation up-to-date that has been recorded much more reliably at another place.