Creating documentation is boring, it's often obsolete and misleading but with a new mindset both your documentation and code can improve, Cyrille Martraire explained in a presentation showing how to create living documentation when working with Domain-Driven Design (DDD) at this year’s DDD Exchange conference in London.
For Martraire the purpose of documentation is all about passing knowledge, to others, for the future and sometimes for regulatory compliance. DDD is about domain knowledge and one example of capturing this knowledge is Event storming which Martraire thinks is an efficient way to discover a domain. Documenting the behaviour, he recommends using Behaviour-Driven Development (BDD) using conversations and concrete example in scenarios. With tools like Cucumber the scenarios can be run against the code which is the first case of living documentation, always in sync with the code.
Looking at the code from a DDD perspective the bounded contexts is already in the code although implicitly and by annotating packages or namespaces Martraire can declare and describe the different contexts, again always in sync with the code. A side benefit that he thinks is really valuable is that he with this technique also can describe different DDD concepts, something he calls embedded learning.
In the same way the ubiquitous language is already present in the code, in classes, interfaces and methods and by annotating the domain-relevant parts he creates a living glossary by using a processor that scans the code after annotations and generating an always up-to-date glossary. In a former project they automatically generated the glossary this way and regularly sent it to the project owners which he believes was a great success.
As an example of documenting a design Martraire uses Hexagonal architecture, with an inside containing only the domain model and the rest on the outside. This pattern is already documented, and by carefully following the pattern in the code he make sure the design is implicitly in the code. Once again using annotations on packages or namespaces he can in the same way as earlier create living diagrams that follows the code.
A big value Martraire finds in these techniques is that if you find it hard to create a living glossary or other living documentation, it’s a signal that you may be doing DDD wrong, a reality check of the code and a way to improve the code through the documentation.
Martraire is currently writing a book, Living Documentation, available on Leanpub.
Next year’s DDD Exchange is scheduled for 10th June 2016 and registration is open.