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.

Time to start Documenting.

[mindhaze]

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!

Brian Jones

[0x0d0a]

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?

Re:Brian Jones

[shaitand]

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.

Re:Wiki for man pages?

[tmtresh]

Isn't that what grokdoc is for, to begin a documentation project? Why don't ya'll just contribute to that?

Re:In other news...

[merdark]

Except that closed source software is usually much better in regards to documentation. Why? Because when people are just 'scratching itches', or whatever the silly expression of the day is, they don't usually care what *others* think. Since THEY know how to use the program, they don't bother with documentation for others. Documentation is not fun to do.

On the other hand, closed developers are forced to make documentation by their superiors. Just becasue you don't find all those windows are make help files helpfull, doesn't mean that they are equally useless for everyone!

Re:Corporate Idiots

[WallyHartshorn]

users simply cannot grasp the concept that skimming through headers and comments in sources is the best documentation there is.

Did you really say that?! "Hmm... I can't figure out how to do generate a table of contents in OpenOffice. No problem, I'll just read the programmer's comments in the source." What kind of fantasy land do you live in? Give me a manual! Give my father a manual! Don't tell us that we'd be better off reading the source code's comments.

This would encourage better design

[billcopc]

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.