Or why a lack of it could be deadly.

A few months ago, I was helping a friend with a project. We were looking for a proof of concept, and didn’t want to build EVERYTHING just to see if it was a good idea. We found out about Company X, and their new product might just fill our needs. Essentially, it operates similar to MailChimp. Drop in some code, and it connects the collected date directly with a backend.

I began looking deeper into Company X, and how to use the potentially timesaving product. And kept looking… And some more. I went through (what seemed like) ALL of the documentation on the site and could not find simple instructions on how to get it implemented.

There were instructions on how to sign up. There were instructions on how to customize the interface that would be presented to the audience. There were mountains of instructions for developers on how to embed the code into projects. (Which seemed counter intuitive as it was intending to simplify a process…) At this point I pulled my friend in, who is more technically savvy than I, and he had issues understanding what was going on.

Luckily the company was small and local, and I was able to contact one of the principals to get a sit down. The gentleman was very nice. We chatted for a bit, he told me about the company, his history, yada yada yada. I began telling him of my woes of not understanding how to use his fledgling software baby. He sits next to me as we go through the documentation. And again. I begin to point out what he does have, an abundance of techno babble.

There is a LOT of information, most of which is not useful to the casual user. Which is what I interpreted the target audience to be. In the end, it took 3 lines of code to utilize the product. Which was literally no where to be found. The documentation has since been modified to reflect this, but I have not returned to see what other updates have been made.

Five minutes ago, I came up with my own thoughts of what needs to be in documentation. This, of course, varies based on the product. For the purpose of this conversation, we will limit it to public facing products/services. Let’s use a car analogy!

Stage 1 – The least amount of energy it takes for your audience to verify the product works. For much of the public, this may be all that is required. Give them a key, show them the accelerator, brake pedal, gear shift and steering wheel. Pat them on the back and tell them to be careful.

Stage 2 – This is for the users who understand your product and want to make some modifications. They may need direction on how to put on some specialty exhaust, a turbo charger, or maybe even a new transmission. In my random guess, this and stage one will cover about 98% of most audiences.

Stage 3 – They might as well be working for the company. At this level, they will want to machine their own heads and parts. They spend free time pouring over whatever they can find and suggest improvements.

Imagine how successful the automobile would have been if all you ever received were technical specs on how forge your own pistons, or vulcanize rubber, but never taught how to drive…

So, there you have it! My 20 minute, off the cuff rant of the proper way to supply documentation. Oh yeah, this documentation has to be presented in an accessible format. If it can’t be found, it will never be utilized. If it CAN be found, it will hopefully alleviate the need to answer individual queries to support, also saving precious time and resources.