Keep knowledge alive – living documentation

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.

At Z├╝hlke we led a fascinating conversation about this topic and here is a first conceptual sketch of how such a living documentation could look like as a storyboard.

(1) A user story map is one way of entering the living documentation. When clicking on an item, you could navigate to e.g. a specific feature within the living documentation associated with this story.

A user story map can be a valuable starting point for exploring a living

A user story map can be a valuable starting point for exploring a living documentation.

(2) In this example, the feature is maintain cart. And this is all the information grabbed from various sources like test classes, test execution results, jira, slack conversations and even manuall edited conceptual documentation.

All information about one piece of functionality at a glance and to drill down.

All information about one piece of functionality at a glance and to drill down.

Automated tests appear with a name derived from the name in the code. And the status from the latest execution can be shown.

(3) When clicking on a UI test, screenshots taken during the test execution are shown.

Screenshots taken during automated UI testing can make a create scenario documentation

Screenshots taken during automated UI testing make a useful scenario documentation.

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

This BDD specification includes annotation where a test failed

This BDD specification includes annotation where a test failed.

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 some detailed documentation up-to-date that has been recorded much more reliably at another place.

Leave a Reply

Your email address will not be published. Required fields are marked *