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.
Man pages, LDP, help files...you name it!
What else could you ask for?
Try Ninnle Linux or NinnleBSD today!
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
So, when this guy wants to install something, he
1. Read the doc
2. Install it on a test box
3. Test it
Impressing, I wonder how much ppl do the same.
Heck why do you think most products comes now with little or no printed documentation ?
#include "coucou.h"
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
I've tried to switch to Linux a few times but I keep running into problems since there doesn't seem to be any good tutorials (short of purchasing books) that tell you how to use it. Not only that it seems that every time I attempt to install a program, I need to find five other programs and for each of those programs I need five libraries in a seemingly never-ending spiral of installations.
Well, it has never been successfully tested.
UI's more important than documentation. You want a sysadmin to use your stuff, don't make him have to search on Google to find what he needs.
"Derp de derp."
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.
Get bent.
Sticking feathers up your butt does not make you a chicken - Tyler Durden
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.
...because if it is hard to write the documentation, that is a clue that the software itself perhaps isn't designed in the best manner...and we couldn't have shocking revelations like that now could we...
It's 10 PM. Do you know if you're un-American?
You actually wrote:
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.
If you weren't just pretending to be a "l33t h4ck3R" to impress your little Slashdot buddies, you would recognize that an open source project like OpenOffice encompasses about 30,000 files and 9 million lines of source code. Yeah, it will be really practical to skim the comments and headers in that, won't it? You can't write software, so quit pretending. If you actually could write software, you would have recognized that many open source projects consist of millions of lines of code and tens of thousands of files -- and you would have never said anything so absurd.
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
I have contacted a couple of smaller projects offering to work on documenting their code, but never got a reply.
I've gotten to the point on stuff like this that I try and avoid projects with bad documentation and/or commenting. I figure if they don't want their project to be usable then they probably don't really want people to be using their project all that bad.
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...
That paragraph about users "reading the source-code for documentation" is the most idiotic thing I've ever read in my life. Unfortunately for you, you had to group it along with a series of intelligent comments above it. Did your brain just crap out that paragraph? I wish I had my moderator points still, because I'd rate this as over-rated.
social sciences can never use experience to verify their statemen
Now, if it wasn't for Gentoo's superb documentation, the number of people who have Gentoo installed would be in the hundreds (if that) not the thousands. Because of Gentoo's excellent documentation, it is possible for a newbie to GNU/Linux (if he knows his hardware) to install Gentoo on his computer.
Without excellent documentation (and very helpful forums), does anyone really think that anyone other than hard-core developers would be capable of installing Gentoo on their computers?
social sciences can never use experience to verify their statemen
"Has it occurred to you that maybe people need to actually understand a product before they can write documentation for it? "
Well I guess that explains why commercial software documentation's so bad. The documentation writers don't understand the product.
Seriously part of being a documentation writer is an understanding of the subject, be it butterflys, or the latest geewizz program. This is a job requirement FOSS pretty much has the same requirement. The writers need to know not just writing, but the subject matter they're writing about.
That means that on one end the writer speaks the language, and on the other translates to an output the audiance can understand.
Now we all know that in FOSS everyone plays their part according to their strengths. The coders code. The artists draw. The testers test. So why are people like the author of the article not playing to their strengths and documenting? One person can't be documenter, artist, UI designer, marketer, customer service, QA, and bring home the bacon. FOSS works because we all help. Not stand on the sidelines, and at best stand silent, and at worst criticize like a mother in law.
Seariously, that "we have someone to blame when the stuff hits the fan" is the biggest fallacy of commercial software ever. The last time a windows security flaw brought down your entire organization (happend to several clients of mine) did Microsoft do anything about it? Did they fix you up and bring you back online? Did they compensate you for lost time? Lost business? Did they even give you a free Windows license?
Nofuckinway. They didn't give you shit. In fact, you prolly had to bring in outside help at considerable expense to get you back online quickly like my last client. Did Microsoft so much as even apologize for writting insecure software? Hah.
So that is why I laugh so hard when some idiot says an advantage of commercial software is some type of corporate security blanket. Trust me, your vendor doesn't care and won't do anything to help you out of a jam when it is clearly the fault of their lousy software package.
"Avoid employing unlucky people - throw half of the pile of CVs in the bin without reading them." -- David Brent
I think you would be completely right if not everytime I'm considering a product to do whatever someone jumps at me and screams "Don't use that ! This is evil closed source ! Use the great open source Wroomdongle ! It will do everything you need, is super secure and will cook you coffee !" When I try to install Wroomdongle, I have to fight more often than not with the often inadequate docu, questions are answered with RTFM (great, the TFM is giving me all that headache) or "oh, you are using 1.1, 2.5 is the place to be ! There all the issues you have are fixed. Oh, one thing: The docu on the Web site is outdated, it only covers 1.9).
Either you just code for your personal fun and give the code away so someone can love it or leave it or you really want to create THE solution for whatever problem (and praise it loudly as such) and accept certain obligations. You cannot have both.
I can't believe what all I have read here in replies. Many times the answer to a question is RTFM and now I'm reading RTF-Source-Code? Come on, people!
I wrote a howto for a build-a-live-cd-on-the-fly called Intellibuild http://ibuild.livecd.net/
iBuild does exactly what I want, but I didn't really have time to read the code, and most people who use it don't either. I realized this and spent hours and hours testing and writing the howto (a bit outdated, atm) and it allows people (who could read the code if they wanted and had the time) to start being productive within a few minutes instead of a few hours.
I wrote a sample howto and sent it to the programmer to show I was serious, which is needed (someone below mentions a lot of blown smoke from volunteers).
The fact is true... OSS needs better documentation, but the developers shouldn't necessarily be the ones doing it. THey should CODE.. that's what they do. An end user that writes the way end users read should document with access to the developer.
There is a Universal Life Value Check it