Living Documentation Step-by-Step

Full day workshop with Cyrille Martraire

Living Documentation Step-by-Step

No dates are scheduled for this workshop. Let us know if you think we should organize it near you, or if you'd like to book it on premise in your organisation.


If you prefer coding over writing documentation, then you’ll love Living Documentation! A Living Documentation changes at the same pace as software design and development, from establishment of business goals to capturing domain knowledge, creating architecture, designing software and coding. It builds on top of BDD and DDD, but it also has its own key principles and novels ways to dramatically improve your documentation at minimal extra cost by using well-crafted artifacts and judicious automation.

This workshop from Cyrille Martraire, the author of the book "Living Documentation" (Addison-Wesley Professional), will guide you on how to implement the approach in your projects. Even if you haven't read the book, this workshop is the right place to learn the main elements of a Living Documentation, step by step through a provided sample Java code base.

Cyrille Martraire at Domain–Driven Design Europe 2017

You will learn:

  • How most knowledge is already there somewhere in your artifacts, even in an implicit form
  • How just talking and working together may be enough documentation, and when it does not
  • How to augment the code to make it fully explicit for further use by people and tools
  • How to differentiate between stable and volatile knowledge, and how this informs the way to deal with it
  • How to create zero-maintainance Evergreen Documents
  • How to recognize Shameful Comments and improve your code from there
  • How a word cloud can tell if you're doing your domain model wrong
  • How to generate a Living Glossary straight out of the code
  • How Architectural Decisions Records can help make better decisions
  • How Design Patterns help document a design decision very efficiently
  • How to visualize a design structure by generating a Living Diagram from the code itself
  • How to use plenty of other techniques to improve your particular needs, and the main traps to avoid
  • How failing to do any of the above is in itself a valuable feedback
  • How to introduce the topic in your project and with your colleagues

What you will need

  • A working Java 8 environment with Maven for two attendees
  • The sample project (only using basic Java) will be available from github or from a USB key
Cyrille Martraire

About Cyrille Martraire

Cyrille Martraire (@cyriux) is CTO and partner at Arolla (@ArollaFr), the founder of the Paris Software Craftsmanship community and a regular speaker at international conferences. With 17+ years of experience in startups, software vendors and banks, Cyrille still calls himself a developer. He's passionate about design in every aspect: TDD, BDD and in particular DDD. Cyrille also has an extensive knowledge of capital market finance, and he's the author of the book Living Documentation published by Addison-Wesley Professional.

No dates are scheduled for this workshop. Let us know if you think we should organize it near you, or if you'd like to book it on premise in your organisation.


Also check out