Agile documentation cheat sheet

Did you notice how people are interested in talking about documentation? I believe it is because they feel a lot of documentation, especially in an enterprise, does not bring any value.
Agile documentation relies on Lean/Agile principles and brings true value to your product or service. At the same time, it must not bring any waste.

Just in time

“Fire and Fury: Inside the Trump White House” by Michael Wolff (Released January 5, 2018) is an instant bestseller and sold over 4 million copies in its first year. It offers insights into Donald Trump’s temperament and decision-making process, as well as the perspectives of top officials and staff members on these matters.

Now … do you think Michael could write this book at the beginning of Trump’s presidency? Stupid question? Then why do you think it is a great idea to document everything at the beginning of a large and uncertain project?

Remember: Historical books cannot be written in advance.

Instead, defer your decision on documentation as late as possible, which means at the latest moment before it could harm your business. For example, describe how your product works just before someone needs to read it. Not earlier.

Just enough

“Perfection is Achieved Not When There Is Nothing More to Add, But When There Is Nothing Left to Take Away” Antoine de Saint-Exupery.

Remember: comprehensive documentation is your enemy. It is hard to use and expensive to manage. It can even harm your estimates!

Here is what you should do:

Before you start writing — STOP!
Think if you really need to document it, or can it be replaced with verbal communication? Remind yourself of agile principle that “face-to-face communication is the most efficient and effective method of transferring information.”

If you really need to document, you should find the bare minimum to “put on paper”. Ask yourself: “Who will use this documentation? What minimum would this person need to read?”

Proven tools like user stories, A3, and others can help a lot.

Just until

Now imagine that you’re preparing to brainstorm with your colleagues. As a preparation, you create and distribute a document describing some early ideas collected from multiple sources. This document perfectly makes sense as an excellent pre-read for everybody, but it doesn’t make sense to update it in the future!

Indeed, much documentation should be abandoned after some time, but we don’t do this. Maintaining such documentation is pure waste.

Instead of treating your docs as permanent, a good approach is to treat it as temporary by default. It is much better to update it only if necessary. Still, you have to ensure that everybody understands the concept that documentation is valid according to the moment when it is updated.

There is a lovely trick on it that I successfully used for years: write most of your documentation as a blog post. People understand the concept of a blog, which is valid when created or updated, but not necessary a long time after it.