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.
Dang, dude. You wrote a rant over 1300 words long complaining about lack of documentation. Imagine if you and similar pundits contributed those words to the documentation of deserving projects.
But, alas, whining is the quicker path.
I watched C-beams glitter in the dark near the Tannhauser gate.
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 am interested in pursuing a career in documentation writing. What better way to earn experience than by writing documentation for open source programs?
I don't feel that I have the ability to write something along the lines of KDE documentation just yet. I would like to start with something small.
If you have an open source program that is lacking in documentation send an email to tjfriese@hotmail.com and we'll see if I can't help you out. If your program has an ebuild for Gentoo, that would be a bonus.
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!
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.
Look, I'll agree that many minor OSS projects could use better documentation, but wouldn't it be easier to submit a list of what you'd like included in whatever product pissed you off than writing a long angry article about it? I mean, there are a lot of obscure little Windows closed-source packages that lack good documentation as well.
I haven't had a problem with major projects.
Is it largefile aware?
I really have seen very few closed-source packages that include this in their documentation, either.
Is it scriptable?
I can't think of any open-source packages that are scriptable that don't document the point that they're scriptable.
Most OSS CLI software isn't explicitly "scriptable" because it can simply be easily run and interfaced with from scripts without requiring an internal interface.
I have refrained from naming names here. It would serve no useful purpose, as my sysadmin colleagues can probably think of exactly the projects I'm talking about (as can the respective coders).
Actually, I'd infinitely have preferred that Brian *had* named the names of the OSS projects that he found at issue, and listed some concrete problems. Then they could be addressed.
The bigger problem for you coders, really, is that there are usually 20 different packages on freshmeat that all do the same thing. Of those 20, probably one or two have real-life, usable documentation.
Your problem sounds more like a lack of comparative reviews to assist you in evaluation than a lack of documentation.
This honestly sounds like the sort of problem you get if you start trying out "mp3 sorters" or "IM clients". I'm dubious that this is a severe issue with, say, webservers.
While I'm posting, does anyone have any idea why Slashdot is changing colors on me like mad? I've seen a rather pretty but less usable gold-and-white theme, and I'm currently posting in a black-and-white theme that says "Don't fear the penguins". CmdrTaco put up a test story on the main page yesterday -- what's going on at Slashdot?
May we never see th
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.
RTFM
* 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.
By having to write documentation, coders might actually realize how frickin' contorted their config files are and try to clean it up rather than have to document hundreds of dark options with "zarp_blorg_snootle = uHb ; This is a hack"
I know it's not 'fun' or 'easy', I code in random bursts too, and my first versions are always "unreadable but it works great!", but if I use the app at all then I do a complete rewrite for the v2.0, since the v1.0 was more of a design-as-you-code exercise, and the resulting code is always cleaner, faster, and much more easily extendable/reusable.
Heck, I did that last week by accident. I had written a fairly long perl script to automate the creation of a full-blown webhosting account (vhost, email, ftp, templates etc). Wouldn't you know it, in my sleepy daze I deleted the script just as I had finalized it. Well I rewrote it in 1/10th the time now that I knew exactly what I wanted it to do, and it was shorter (more modular functions) and less bug-prone.. I even threw in a few command-line options so I don't have to edit the config file all the time.
It's daunting, but some big projects could really use a fresh start, with proper documentation maintained from the beginning.
-Billco, Fnarg.com
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...