A few years back I was arguing in forums around the 'Net that Linux would not be embraced by the masses until at least a couple of problems were fixed - that is, Plug and Play support and bad/no documentation. The first is fixed - Knoppix and Ubuntu, just to name a couple, will recognise and install every device that I have, as long as it is not some brain dead "WinModem/WinPrinter" type of junk. (Now as far as the "masses" adopting Linux, I am not sure what the Linux community will gain if several hundred million non-technical icon clickers come on board, except maybe more driver support by manufacturers, but that is for another thread).

As to the second problem (documentation), it is definitely not fixed. I know the reason (I am guilty of it also) - programmers hate writing docs, and programmers writing free GPL code have nothing pushing them to write it. So they (we) throw together a few pointers, call it documentation, and assume that the new user will have the patience to hack away until it works. Not always - several times in the past I have decided that trying to figure out how an apt was supposed to work, or be installed, wasn't worth the value that the apt was supposed to supply.

Recently I helped a friend install a MUD game server application. I won't name it because its documentation is no worse than many other Linux apps. It was a very intensive application and apparently widely used. The problems...

The abbreviated man page was useless with nothing but a few options for starting the program.
The docs that were delivered with the package were empty skeletons. Nothing but "To Do" statements.
The website documentation link had... you guessed it. "This document is under construction". Alas, the last date on the doc page was 2005, even though the last update to the actual application was only a month or so old which indicated that development was still active.

I ran across one doc file that actually has the statement "I really need to write this someday."

A dedicated techie who really wanted this to work would start taking scripts apart and using the old 'try and die' method of hacking away would eventually get it to work and know all about it when he/she was done. But most of us have other things that several dozen (or hundred) hours need to be used for.

That is the no documentation problem. The other is bad documentation. This can be broken down into several types - too abbreviated, too technical, or pure sanskrit.

Here is an example from the README for a utility apt...
"...be warned that dynamic paging will cause an implicit ongrab, override with dograb or nograb." Wow, this is really great info for the intro section of a README file, especially since nowhere does it mention ongrab, dograb or nograb or how and where to use them. Are they command line switches and I need to put a "-" in front of them? Who knows? This, and a whole lot more, should be in the source at the statement that causes the problem.

If I am actually looking for a README file, it means that I know nothing about the application yet and am trying to get it installed and running. Telling me that the fligit has to be mortificated with the glitzer module (use the -xyz switch unless your fleewarz is enabled) is of absolutely no help and sometimes can cause a knee-jerk reaction of apt-get uninstall, or RPM -e. Most Linux users are not programmers who can take apart the code in an application and figure out how it works - and don't want to be. Heck, I have trouble enough trying to figure out code that I wrote myself.

Some package programmers genuinely try to supply docs, but they are almost always writing at too high a level. The main problem with this person is that they don't bother writing about the obvious, not realising that what is obvious to them takes hours of googling to make sense to their audience. The one program that I have published had what I thought was very in depth and easy to understand docs supplied - in fact, I spent a lot of time on them. But I still got gigged every now and then for "Insufficient/incomplete/confusing documentation."

Note*** None of the above is to claim that WinDocs are perfect, by a long shot - I defy anybody, including the original programmers, to install the early IBM Websphere or Lotus Suites by using the install instructions! This isn't just a Linux problem - when our local school district started using Delphi for computer science (years ago), the manual was virtually rewritten by the instructors because the beginners Help section was incomprehensible to anybody who wasn't an Object Pascal expert.

Anybody remember the Heath Corp? They made wonderful electronic kits (Heathkits) that were not only high quality, but the associated documentation was award winning. I read that before a new kit hit the market, a non-technical person (like a secretary, maybe) was given the kit to put together. So that where the instruction of "Install diode D1 with the cathode toward the top of the printed circuit card" made plain and totally unambiguous sense to the designer engineers, the novice might ask "What is a cathode?". Then the instruction would be changed to "Install diode D1 with the cathode (the white bar) toward...).

Now, Linux users probably don't want a comic book approach to documentation - if they were that type they would be using Windows. But even a guru usually needs something besides a few lines of cobbled together programming notes.

So, the above is a list of complaints. What are the answers?

I don't know. If I PURCHASE a software package, I have the right to throw rocks at bad documentation. But, with Linux, we are usually getting high quality software that is both free and Free, and it would be highly impolitic to b***h about the lack of something - somewhat akin to loudly complaining about a birthday gift. But developers need to realise that better docs might cause a far higher acceptance of their work. Especially when you are trying to convince your IT director that a particular Linux utility is solid, free, and a perfect fit for the organization.

You. "This Linux utility is solid, free, and a perfect fit for our organization."
Him/Her. "Great, let me see the manuals."
You. "...Uh, Well, it just has this 12 line README file... But the actual documentation is coming REAL SOON."
Him/Her. "Get out."

Konan