Documentation is another deliverable and 7 other rules

“Working software over comprehensive documentation.” The Agile Manifesto

Some have taken that line to mean “no documentation.” I have sympathy for that. Years ago I worked on railway privatisation in the UK. We (Sema Group) were building a system for Railtrack – remember them?

We (the programmers) had documentation coming out our ears. Architecture documents, design documents, user guides, functional specifications, program specifications, and much much more. Most of the documentation was worse than useless because it gave the illusion that everything was recorded and anyone could learn (almost) anything any time.

Some of the documentation was just out of date. The worst was written by architects who lived in a parallel universe to the coders. The system described in the official architecture and design documents bore very little relevance to the actual code but since the (five) architects never looked at the code the (12) programmers could do what they liked.

Documentation wasn’t going to save us.

But, I also know some documentation is not only useful but highly valuable. Sometimes a User Manual can be really useful. Sometimes a developers “Rough Guide” can give important insights.

So how do you tell the difference?

How do you know what to write and what to forego?

Rule #1: Documentation is just another deliverable

Time spent writing a document is time not spent coding, testing, analysing or drinking coffee. There is no documentation fairy and documentation is far from free. It costs to write and costs far more to read (if it is ever read).

Therefore treat documentation like any other deliverable.

If someone wants a document let them request it and prioritise it against all the other possible work to be done. If someone is prepared to displace other work for documentation then it is worth doing.

Rule #2: Documentation should add value

Would you add a feature to a system if it did not increase the value of the system?

The same is true of documentation. If it adds value then there is every reason to do it, if it doesn’t then why bother?

Rule #3: Who will complain if the document is not done?

If in doubt identify a person who will complain if the document is not done. That person places a value on the document. Maybe have them argue for their document over new features.

Rule #4: Don’t write documents for the sake of documents

Don’t write documents just because some process standard somewhere says a document needs to be written. Someone should be able to speak to that standard an explain why it adds more value than doing something else.

Rule #5: Essential documents are part of the work to do

There are some documents that are valuable – someone will complain if they are absent! User Manuals are one reoccurring case. I’ve also worked with teams that need to present documentation as part of a regulatory package to Federal Drug Administration (FDA) and such.

If a piece of work requires the documentation to be updated then updating the documentation is part of the work. For example, suppose you are adding a feature to a system that is subject to FDA regulation. And suppose the FDA regulation requires all features to be listed in a User Manual. In that case, part of the work of adding the feature is to update the user manual. There will be coding, testing and documentation. The work is not done if the User Guide has not been updated.

You don’t need a separate User Story to do the documentation. In such cases documentation may form part of the definition of done.

Rule #6: Do slightly less than you think is needed

If you deliver less than is needed then someone will complain and you will need to rework it. If nobody complains then why are you doing it? And what value is it? – Do less next time!

This is an old XP rule which applies elsewhere too.

Rule #7: Don’t expect anyone to read what you have written

Documentation is expensive to read. Most people who started reading this blog post stopped long ago, you are the exception – thank you!

The same is true for documentation.

The longer a document is the less likely it is to be read.
And the longer a document is the less of it will be remembered.

You and I do not have the writing skills of J.K.Rowling, few of us can hold readers attention that long.

Rule #8: The author learns too

For a lot of documentation – and here I include writing, my own books, patterns, blogs, etc. – the real audience is the author. The process of writing helps the author, it helps us structure our thoughts, it helps us vent our anger and frustration, it forces us to rationalise, it prepares us for an argument, and more.

So often the person who really wants the document, the person who attaches value to it, the person who will complain if it is not done, and the person who will learn most from the document is the author.

Join my mailing list to get free updates on blog post, insights, events and offers.