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
