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.
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
About the instructor
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 to be published by Addison-Wesley Professional.