It's the Documentation, Stupid!

Roblimo writes "Brian Jones, a sysadmin for Princeton University, has written a Linux.com column that says open source developers need to provide better documentation if they expect support from sysadmins like him: 'With documentation, I can get to know the software,' he writes. 'Then I'll install it on a test box. If it works, great, I'm tickled pink. If it doesn't quite work, then I'm interested in giving feedback, because here's someone who will roll it back into the product or the documentation. This is a useful cycle that benefits millions, not the least of which is the coder! Documentation ends up resulting in a more mature product! Wake up!'"

Comments

I want to write docs

[kisielk]

I've been trying to find a project to write docs for for quite some time, but I usually don't get any replies when I email authors of various software. If they don't want to communicate with me I don't want to be wasting my time writing documentation for them.

So how about this, if you have an OSS project that needs some docs, contact me. If I find it interesting maybe I will help out.

Maybe someone should set up a site where doc writers can offer their services and software authors can request to have docs written for their programs. Just an idea.

He's half right

[dacarr]

It's not just open source, but closed source. And the problem I run into when looking at software is what I call Oualline's Law of Documentation:

* 90% of the documentation does not exist
* Of the remaining ten percent, 90% is obsolete or inadequate
* Of all the documentation, the remaining 1% is written in a foreign language you cannot understand.

We know about the first and third points, but on the second point, it's either missing examples (i.e., man pages, as another user cites), or just tells what you can do with it and little else without bothering to take you through the steps (much closed source), with explanations on what certain functions do that are vaguely important.

To note, the "law" was published in Steve Oualline's Practical C Programming by O'Reilly books. I modified it slightly - the third point notes "Chinese", but there's a good probability that somebody reading this can read Chinese. =)