Living Documentation by design, with Domain-Driven Design

by Cyrille Martraire

Accelerate Delivery Through Continuous Investment on Knowledge

You don't necessarily have to chose between Working Software and Extensive Documentation! Discover how a Living Documentation can help you in all aspects of your projects, from the business goals to the business domain knowledge, architecture and design, processes and deployment, even if you hate writing documentation.

The approach "Specification by Example" has introduced the idea of a "Living Documentation". In this approach, examples of behavior are used for documentation and are also promoted into automated tests. Whenever a test fails, it signals the documentation is no longer in sync with the code so it can just be fixed quickly.

This has shown that it is possible to have useful documentation that doesn't suffer the fate of getting obsolete once written.

But we can go much further. This book expands on this idea of a Living Documentation. It shows how a living documentation evolves at the same pace than the code, for all aspects of a project, from the business goals to the business domain knowledge, architecture and design, processes and deployment.

This book explains the theory and describes a number of techniques, with illustrations and concrete examples. You will learn how to start investing into documentation that is always up to date, at a minimal extra cost thanks to well-crafted artifacts and the use of automation.

Genres: Programming, Technology, Software, Nonfiction, Technical, Computer Science, Business

289 pages, ebook

First published October 1, 2015

Reviews

[Jevgenij · Rating 4 out of 5]

There are so many interesting ideas in this book, the only downside is that the author tries to mention EVERY SINGLE ASPECT of software development in context of documentation - debugging, refactoring, architecture - it's all there, which creates a big mess out of the narrative and unfortunately removes much emphasis from the good ideas that actually matter.

[Matthijs Thoolen · Rating 5 out of 5]

This is a must-read book to read for anyone doing software in a non-trivial environment. It explains with humor and good examples how to capture knowledge about a problem domain in and around a software project.

[Sebastian Gebski]

Supposedly 95% done (when I was reviewing it), but TBH it's the most unfinished book of all MEAPs I've ever read (& some were ~50%) - plenty of repetitions, intermittent narratives, etc. Sometimes I had a feeling that Cyrille is trying to rephrase exactly the same thought he did few pages before. These feeling were amplified by the length of the chapters - initial ones were long & elaborated, while the final ones are nothing more than 2-4 pagers.

Somewhere there, behind the flawed form, there's a good content. Valuable content that truly makes a lot of sense. But for now, it's quite painful to dig it out, hence no starred review. If you want to read "Living Documentation", wait for the final revision.

[Johnny · Rating 4 out of 5]

How can we keep documentation up-to-date, when writing it is one of the more boring tasks in software development? Cyrille Martraire offers an interesting approach called living documentation. Instead of creating text documents by hand, they are created automatically. If the code you write is enriched with additional information to generate the documentation out of it, then you don’t have to write it. And even better, you don’t need to update it manually. All you do is to start a build and as a side task the documentation is updated.

I like this idea very much, but unfortunately are the examples on how to do it in practice a bit too thin for me. More details and an example in .Net would be of great help for me.

[Alessandro Ronchi · Rating 4 out of 5]

It took me a year to read the book cover to cover.

It's full of advice. I took notes and highlighted many paragraphs.

And it's just the beginning, now it's time to put all the knowledge into practice.

The author repeats some concepts repeatedly; it is good in this case. He also delves into DDD, BDD, and communication, which makes the content even more valuable.

The main takeaway is: by starting with a practical approach to evolving software documentation, you end up with a better design.

[Bart Schotten · Rating 4 out of 5]

Filled to the brim with interesting ideas. You can tell that Martraire is not a native English speaker, but all in all it's decently written.