Thoughts about… Good Documentation

Documentation. Everybody wants it when it is missing, everybody hates it when it is bad and nobody likes to write it.

What is bad documentation?

Documentation can be bad in various ways. It can be plain wrong, its language can be obscure, it can be too little or to much, it can be incomplete or there is non at all… the simple common criteria which makes documentation bad is, it simply does not help. It does not really matter if the information I need is there and I just don't find or understand it, or if it is missing at all. What matters is that it failed for me.

What is good documentation?

The perfect documentation contains exactly what I need to know and nothing else. It is written in my language and I understand every single word the way it was meant.
Obviously, perfect documentation is something quite close to impossible. Real documentation will at the very least always contain answers to question that are not mine.

But why is real documentation often not even remotely close to perfect documentation?
Well, who writes documentation? In my career very little documentation was not written by developers. Some got edited by technical writers or at least somebody with better spelling skills than the average developer. Some got a more professional layout and the images might get more colourful. However, the core content of it was almost always written by developers.

Do you know how developers work? Developers are used to write code. They write some lines then they try to compile it. Afterwards they might even execute a test, which tells them if the code works as expected.

There is only one way to achieve something similar for documentation: you got to give it to humans and ask if they like it. To achieve something like a test you also need to monitor if they are able to use the product after they read it. Of course, humans are not standardised. A documentation perfect to one may be really bad for another and certainly humans involved in the product development process will have quite helpful knowledge nobody outside development could possibly have.

It might be a little difficult to verify all documentation like this but developers – and I think most other people as well – certainly like verifiable tasks with a limited scope. Ideally any task should conform to the INVEST criteria. A task description like

Write a complete and well readable documentation.

does certainly not. What is complete and readable by whom? That's why nobody likes to write documentation and that's why the results are often quite bad.

Another reason is that in waterfallish project documentation – just like tests – is a late task. So there is a lot of it to do once the task gets into progress.

The solution here is the same as for tests and features: write you documentation in increments. Whenever you get the task to finish a use case don't rely for the Product Owner to ask for documentation but suggest it yourself if necessary.

How to Improve?

Test your documentation as good as possible. If you get the trivial formulated documentation task (like above), try to gather more information. Ask who will need it and for what. Which use cases need documentation? Are there multiple user groups with different scopes? If yes, should there be a separate documentation for each of them? Are there users at hand who might deliver more specific questions? Can they even test the documentation? Try to do test driven documentation. Documentation is just like code you write for human brains instead of compilers.

When you practice this you will quickly notice that there is not so much documentation at all. Most of the documentation I wrote was never written because the recipient simply had something different in mind. Once I delivered exactly what was needed the total amount reduced dramatically.

So whenever you show an increment of your product, handout the documentation for it, so the user can verify the feature itself but also its documentation and how well it will be understood by the users of the software.