BT

Your opinion matters! Please fill in the InfoQ Survey!

DDD and Living Documentation

| by Jan Stenberg Follow 9 Followers on Jun 15, 2015. Estimated reading time: 2 minutes |

A note to our readers: As per your request we have developed a set of features that allow you to reduce the noise, while not losing sight of anything that is important. Get email and web notifications by choosing the topics you are interested in.

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.

Rate this Article

Adoption Stage
Style

Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Tell us what you think

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Always relie on developers by Erik Gollot

Very interesting webcast. It makes me remember to an old UML tool TogetherControlCenter in which the storage format for the model was the java code itself. They used annotations (javadocs @ it was before java annotations).
But one of the problem is who write in the code ? The developer.
And in an organization where you've internal analysts and where the coding is delegated to subcontractors, it's not so easy to wait for the code to discuss on tour DDD model. You also needs to brainstorm before writing some code, ok maybe we've the walls...
Not totally convinced but find the idea really interesting
Thanks

about by Luis Valdes Guerrero

this is nothing new, Knuth propose include doc into code in his publication "Literate Programming" long time ago

about by Luis Valdes Guerrero

this is nothing new, Knuth propose include doc into code in his publication "Literate Programming" long time ago

about by Luis Valdes Guerrero

this is nothing new, Knuth propose include doc into code in his publication "Literate Programming" long time ago

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

4 Discuss

Login to InfoQ to interact with what matters most to you.


Recover your password...

Follow

Follow your favorite topics and editors

Quick overview of most important highlights in the industry and on the site.

Like

More signal, less noise

Build your own feed by choosing topics you want to read about and editors you want to hear from.

Notifications

Stay up-to-date

Set up your notifications and don't miss out on content that matters to you

BT