Documentation for human beings

coffee_compI am not going to bore you with – you have a good product and an incomprehensible documentation… blah blah blah. Let’s talk about the case where you do have an excellent product and an excellent (at least that’s what your technical architect thinks) documentation to go along with it. The product sold reasonably well but then, all of a sudden, your developers keep getting bugs from the customers those are often invalid. To your surprise, things are actually explained as far as possible in the documents (I mean it literally). Your developers keep whispering to each other – don’t the customers read the documents?

I realized the problem when I was going through a document of a product. When the developers who wrote the software were working on the inputs for the document, they did their best and provided every possible detail to help out customers. However, the only thing they missed – the documentation was no longer humane. While that goes well with manuals for small utilities where the bulk is much lesser, it doesn’t play well with products.

Your customers are human beings and 90% of them will have no patience to keep reading through the document if you can’t keep them glued. Most people love to learn on the job as they have confidence on their technical capabilities. So they don’t like to read through hundreds of pages of documentation. And when there’s a mismatch between your developers’ reasoning and your customers’ expectation you have a new issue filed.

So how do you avoid it? First things first – don’t make your developers write the documentation. Robots can’t make love as a general rule. So don’t take the risk with your business at stake. Have some expert write it with inputs from them. Next, keep it a jolly document, not a huge list of DOs and DON’Ts. Another wrong notion is – corporate documents must be very formal. NO. Try being a bit informal, add light humor to it occasionally. Finally, try your own potion: make people in the organization read it – testers, other teams, busy managers… and have the feedback.

One of the manuals/documents I absolutely love is man top¬†and I think it’s a great example of how documentation should be. Run quickly through it till the end and you will see what I mean.

2 thoughts on “Documentation for human beings”

Leave a Reply

Your email address will not be published. Required fields are marked *