BT

InfoQ Homepage News DDD and Living Documentation

DDD and Living Documentation

This item in japanese

Bookmarks

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

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

Community comments

  • Always relie on developers

    by Erik Gollot /

    Your message is awaiting moderation. Thank you for participating in the discussion.

    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

  • Your message is awaiting moderation. Thank you for participating in the discussion.

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

  • Your message is awaiting moderation. Thank you for participating in the discussion.

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

  • Your message is awaiting moderation. Thank you for participating in the discussion.

    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

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

BT

Is your profile up-to-date? Please take a moment to review and update.

Note: If updating/changing your email, a validation request will be sent

Company name:
Company role:
Company size:
Country/Zone:
State/Province/Region:
You will be sent an email to validate the new email address. This pop-up will close itself in a few moments.