Living Documentation: Continuous Knowledge Sharing by Design

by Cyrille Martraire

Software documentation: a necessary evil? It needn't be! Documentation can come to life, evolve, stay dynamic, and actually help you build better software. This concise guide introduces and thoroughly illuminates the concept of living documentation that changes at the same pace as software design and development, from establishment of business goals to capturing domain knowledge, creating architecture, designing software, coding, and deployment. Replete with clarifying illustrations and concrete examples, it shows how to dramatically improve your documentation at minimal extra cost by using well-crafted artifacts and judicious automation. Language- and technology-agnostic. Living Documentation borrows powerful ideas from domain-driven design, helping you customize its concepts and apply its lessons to meet your changing documentation needs in your own specific domain. Cyrille Martraire proves that you don't have to choose between working software and comprehensive, high-quality documentation: you can have the benefits of both.

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

480 pages, Hardcover

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.