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!
#!/
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.
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."
I wrote a small app recently, and have been less than pleased with the response. I figured there were more people out there with a need like mine.
The app is Jaio, which renames digital camera images according to their EXIF data.
That being said, I included very little documentation for the thing, and hardly documented at all the algorithm I used, since to me it was kind of common sense.
I think after reading this article, I'm going to write some more thorough docs, and then include those docs in the help menu.
Thanks Brian, for the inspiration!
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.
The 10 laws of documentation of an GNU program:
.conf file.
1. Add a 3-line FAQ for expected "bugs"
2. Add "We need documentation authors" to README
3. Wait for documentation to be written when you are finished with v1.0
4. Delay documentation since it would break with the current v1.1 development
5. You don't bother doing the documentation, since you've allready documented most in the source.
6. When it works, you just publish the source and hope somebody else will do the rest.
7. Make a website, create a logo and start having a nice time making design and stuff. When finally creating the documentation/index.html, just add Under Construction, since what you really want is a even better logo.
8. Write some complex documentation, and hold back the real tutorials and publish them in a book.
9. Spend some time with emacs, to finally understand that it sucks to write documentation when you have to think of line-breaks in a text document.
10. Include an myfile.conf.example which you think will cover most questions anyway. Do forget on purpose that many lines need linebreaks at end of text, even if it's the last line. And also forget to add that TAB's are not supported in your
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.
* 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.
While I'm sure there are a couple small projects with crap documentation. There are no shortage of LARGE projects with crap documentation.
mysql (almost all the documentation is wrong, and I mean the simplest stuff is wrong, like working with authentication). They have lots of documentation, but most of it is inaccurate, out of date, and in many cases was ALWAYS wrong. They rely too much on the ability of users to comment on given pages of documentation. But those users are wrong half the time, and even when they are right their contributions don't seem to ever be added.
Apache, dear god just look at it. Their documentation is basically a quick reference, they list all kinds of options and generally out of context. Have these people never heard of tutorials?
Bind... bind is scarey as hell, you find conflicting and inaccurate information EVERYWHERE not just on the website. For instance, look for information on how to setup reverse lookups. You won't find any actual tutorial type information at all, explaining simply how reverse lookups work and giving a couple examples. Nope, what you'll find are lots of people posting new information about old versions of bind. They give incorrect syntax that simply doesn't work almost every time.
Thinking about it, I can't honestly say I've EVER found a bind example on the web that worked without modification. From ANY source.
I've yet to find a ftp server with good docs either, again the same problem. In the case of ftp servers they seem to have an obsession with large anonymous ftp (aside from universities and large software vendors who actually wants to do this?).
If any other option they give the ability to have users log into their system accounts home directory, talk about a pain in the arse to manage and keep seperate from other services. I suppose if you were doing web hosting this is what you'd want, but not for anything else.
Most things assume that actually using the software is obvious, or the other way, they assume you've had no problem installing.
Very few give configuration examples. Some sites give a couple limited examples but don't give examples of usage for the config options. Some give the config options but no configuration examples, like apache. Some do either of those or both but don't cover how to install the software.
COMPLETE Documentation is needed, that covers everyone from complete novice and idiot who nothing nothing about the app or the OS to power users who know nothing about the app. Even advanced documentation should be written from the perspective that the user knows nothing about the app.
Because after all an advanced user, who knows alot about webservers and nothing about apache, is going to be looking at adanced topics the first day they are playing with apache.
The docs should take you from novice to guru, include tutorials, include a hand hold through installation.
References are good but they don't replace the need for any of the rest of it.
The docs should also always apply to the latest stable version, if the docs havent been checked and updated, then the new version isn't stable yet. The docs should be considered part of the release.