Maybe you know this situation: You find an interesting software that is worth to play. After you’ve installed it there are two possibilities: either the software is (a) very easy and self-explanatory, or (b) it is very complex.

As most software fall into category (b), one way to get used to it is you can play around and discover it by yourself. Sometimes it works, sometimes not. In case you need help, you can either ask a programmer, or write a post to a mailinglist or forum. But when you need an answer for your question now what else remains? Right! You need documentation!
And with documentation, I mean good documentation. Not something with “Documentation? Use the source!”

Although it seems obvious, I’ve learned this lesson again some time ago, when I tried to use Python bindings for Subversion. Yes, there is a subversion-python package, but there is no documentation. No API documentation, no quickstart, nothing. Maybe the situation has changed now. I tried to find some examples in the Internet. Nothing. Simply I couldn’t use it and I haven’t had the time to discover the inner working of this piece.

Another example: A lot of KDE programs come with, at least, some documentation, but this is not always the case. You can display it from the Help menu. What I observed from these documentation, they mostly describe the software: “Here is this, here is that.”
“Why should this be wrong?”, you ask. Well, in my opinion the mere description of a GUI with all its menus is not what I consider efficient. Come on, this is boring! I can see the menu right in front of my nose! 🙂

But what is good documentation? I collected a list — very likely not exhausting — which I consider good documentation:

• It is easy to read.
  Well, this should be obvious. But it is always difficult to write clearly and to the point.
• It tells me how to solve problems.
  As I wrote before, in most cases it is useless to describe GUI menus in great depth. I prefer a “problem-oriented” style: here is a problem, there is the solution.
• It gives me step-by-step instructions.
  When software is a bit more complex, it helps a lot to solve a complicated task with some small steps: “First do this, then do that and then …” I can check every step to see if I completed it successfully.
• It is targeted to its audience.
  A lot of documentations don’t know their audience. An API documentation is very likely to be read by a developer, so it is perfectly ok to use acronyms or technical terms that is well-known to this group. On the other side, a quickstart that explains the installation of Linux for a Windows user needs more thoughts on style and what is acutally known.
• It is typographically and aesthetically attractive.
  Although this has nothing to do with the content of documentation itself, I consider it nevertheless important. Good documentation accompanied with good typography is better to read and understand. Bad typography annoys the reader or even creates misunderstandings in the worst case (“Does this line belong to the listing?”)

So, what’s the consequence of this? Good documentation saves me time. With more time I can try out more things and concentrate on my task or problem.

Complicated software without good documentation is very likely to be unusable. I guess, without good documentation, users are unhappy and turn away from it.

So how do you “measure” the value of documentation?

Both comments and pings are currently closed.

• Tags:Documentation
• Category: Documentation