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.
(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.
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.
(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.
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.