Slashdot Mirror
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!'"
someone writes an article saying closed source developers should do the same!
#!/
Why isn't there a wiki for the man pages?
The biggest problem I have with the man pages, is lack of examples!
--
Original, Fun Palm games by the Lead Designer of Majesty!
http://www.arcanejourneys.com/
I've changed from doing research at the university to a international company and to my regret and complete surprise, the sysadmins from that company are far from, euh, gifted.
The comporate policy seems to be that anything that costs lots of money must be fine while something which you can download from the internet cannot be anything but bad, inferior and buggy software.
Who cares if e.g. lots of money are spent re-routing corporate e-mail to off-shore server (for a spam solution) instead of installing spamassassin and clamav. But one of the most unfortunate things I have had the bad luck to witness, was an official meeting to evaluate two software packets. One was completely open source and collaborate project while the other one was a commercially branched solution. The meeting had 8 engineers attending a 3 hour meeting evaluating the packet presented by the sysadmins, who had obviously already made up their minds, since the column of the free solution was not even filled out. Finally it boiled down to
The software costed only 250 Euros...
Some (esp *cough* power users *cough* of some commercial *cough* operating system *cough*) users simply cannot grasp the concept that skimming through headers and comments in sources is the best documentation there is. All other documentation is out of date and is certainly not that reliable and often in contradiction with the program and functionality.
This kind of corporate complete braindead reasoning is ubiquitions. Unfortunately, this is corporate IT, not always done by the best and brightest. At least, it really made me to appreciate those good admins out there and you can praise yourselves lucky if you have them...
Genius doesn't work on an assembly line basis. You can't simply say, "Today I will be brilliant."
Noone wants to read another fucking whine piece by some asshole who likes to hear himself talk.
So why'd you write it, then, if you realize no one wants to read it?
Quidquid latine dictum sit, altum sonatur.
I think documentation in general is hugely important. Not just for people who are not programmers but who are sysadmins, like the author, but for any programmers who want to contribute to the code.
I actually haven't run across major usage documentation problems like the author of the article did -- I have been able to install and run many of the programs I want to, without significant trouble. The problems I run into are when I actually want to dig into the code to change something. I am usually bewildered by the size of the project and I don't know where to start.
Documentation is good. I like writing documentation for my code (and I feel like I'm somewhat rare). But it's something that I naturally do at this point. I don't consider it a 'chore' or anything like that -- in fact, I enjoy writing docs for my code that I understand, in order to communicate this understanding to others.
I think that code documentation, not just usage docs, is a core part of the open source development model. If you are the only one who can understand your code, then chances are that your project will die if you stop maintaining it. The mental model is very important in programming, and others' capability to replicate your model in their minds will help them write integrated, less buggy code for your project.
Better documentation is clearly needed. It doesn't have to be dumbed down for 3-year-olds, but you shouldn't expect every user to be an accomplished C programmer, either. Somewhere in the middle is fine. Documentation that can be understood by a fairly smart, experienced, non-programmer is usually sufficient. Joe may be the master, but Joe is in Munich this week and Frank the network guy here needs to make a configuration change ASAP. If Frank can't do it without taking a C class and studying a large, obscure API reference for days, there is definitely a strong need for better documentation.
Has it occurred to you that maybe people need to actually understand a product before they can write documentation for it? Now, who understands better how a piece of software works: the original developer(s), or potential customers?
It's tough to write good docs. Once a client of mine wanted very thorough documentation (API docs, user's manual, etc) for a project beyond the README's and INSTALL's I usually bundle with the code.
I immediately doubled the estimate. Why? Because you are basically writing the logic of the app all over again, except in this funny programming language called "English". And when you update one you have to update the other. Not to mention you have to update your unit tests too (which is another thing most programmers don't do).
I'm not trying to make excuses or saying that we should skip documentation, it's just that it doesn't "scratch the itch". I don't believe that open source exists because of altruism, but because somebody solved their own problem and didn't keep it from the world. So we need folks who are truly interested in documentation (like technical writing geeks).
As open source grows we need to find all sorts of folks: technical writers, usability experts, designers, artists, testers.... we should also not be afraid to hold "fundraisers" to hire an outside team to do this. Wouldn't it rock if Mozilla, KDE, Gnome, etc., had a *thorough* going over with a talented usability team?
Anyway there's one concrete piece of advice I can give any open source programmer, especially if its not a gui-based tool: PUT EXAMPLE USAGE ON THE FRONT PAGE OF THE WEB SITE!!!
This annoys me to no end. Too many sites just have blocks of text describing how great their stuff is.. but no example of setting up a config file, running it from the command line, etc.
I would love to see a step-by-step up and running document, nothing fancy. Show some examples of what your config files and so forth look like. How about screen shots of command line operation? If it's too complicated to show in a few pages, *simplify it*.
The quicker I can get your program up and running, and the less work I have to do, the less I have to hack in my existing configs and so forth, the faster I will be sending you patches.
Positive example: The awesome Ruby on Rails framework has a setup *movie* showing exactly how to go from zero to app in 10 minutes. I wish all projects had something like that, and more importantly, I wish all projects were SIMPLE enough to demo in a few minutes.
Negative example: I was wondering if Perl's Template Toolkit was the right template system for me. I was looking for a very basic kit that could mix Perl directly with HTML (a-la PHP) with no fluff and bloat. I couldn't see any example on the front page and after a minimal amount of searching, I still had no idea what it was like to actually *use* the damn thing. Just bullet lists of features (which are shared by pretty much all similar systems).
So, as a first step down the road of good documentation, try this user-focused idea: give some examples up front.
Has it occurred to you that maybe people need to actually understand a product before they can write documentation for it? Now, who understands better how a piece of software works: the original developer(s), or potential customers?
Then again, who usually does a better job explaining how to use it to newbies? The developer or another ex newbie who has worked out how to use it?
* 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. =)
This sig no verb.
Maybe it's just the tone of the parent's post that got it modded "Troll", but if I had mod points today, I'd probably be modding this "Insightful" instead.
Not every developer's goal is to advance OSS. I have no data to back this up, but it seems to me that many probably just wrote a program to do something they wanted. The fact that they released it in hopes that others may find it useful should not obligate them to cater to every person that feels that they have the right to have their hand held while they use said program.
I'm not going to lie and say that good documentation is not needed. It is. In many places it's lacking. I'm not going to say that I look through the source code any time I try to use a program with little/no/bad documentation. I usually don't, and just look for something else. But to assume that every developer of an open source program needs to dedicate their time to something that YOU want is a little selfish, IMO.
I wonder how many of these people that whine and complain about bad documentation have actually written any documentation OR code. They obviously feel the need to write something though, so maybe instead of bitching about the situation, they should do something to improve it. Of course, I think we all know which is the easier of the two options...