Is Linux Documentation Lacking? 769
eldavojohn writes "A number of blog posts are surfacing that are calling out the helpful open source community on their documentation. No, not the documentation for the highly skilled technical people, but the documentation from beginner to apprentice. A two-part series by Carla Schroeder lists bad documentation as 'Linux Bug #1' and advises users to use Google as the documentation. We've discussed before some of open source's documentation being out of date. Is it really as bad as these blogs paint it? Has it come down to using Google before a man page?"
Of course it is. (Score:5, Interesting)
But on the flipside, I tend to use Google as the documentation for Windows/MacOS and most assorted non-free software that runs on them, too.
Don't like man pages. (Score:5, Interesting)
I find man pages to be poorly written, and difficult to understand most of the time. I tend to use google to find people who are discussing it in plain english...
Re:Yes it is terrible! (Score:1, Interesting)
I haven't seen any difference with windows systems. On mac at least you have the initial link to the online tutorials.
Re:It's better than Mac OS X documentation (Score:3, Interesting)
or help files for that matter. But I don't think this is really the problem. It's how often does the user feel compelled to consult the documentation or help files in their normal daily work that matters.
I'm guessing you're referring to the printed documentation only.
Apple's online knowledgebase is unsurpassed, since it covers both hardware and software, and since there are so few permutations of both that it's possible to actually have comprehensive documentation.
And the built-in, offline help system is pretty darned good for basic purposes. For other purposes, it searches the above mentioned online knowledgebase, so...yeah.
Documenting shitty software is futile (Score:2, Interesting)
If a software solution is crappy enough, it is impossible to write document for it. If a program has to be *endured* rather than enjoyed, all its documentation can do is either reinforcing the shittiness experience by point out *how* and *why* it already sucks and un-amendable (if the doc is correct), or dumping more crap on top of that (if the doc is incorrect).
I'm looking at you, GNOME. I used to be a GNOME user but I gave up. The docs was barely useful for anything. I wanted to configure GDM and there's no explanation of those arcane XML shit and event hooks. The conf files were scattered here and there, and guess what, the infamous, incomprehensible gconf that actually brags about being modeled after MS registry! I finally got the idea that the devs simply gave up the idea of explaining their un-explainable clusterfuck already. I don't use a DE anymore.
Mod me however you want. I'm not a karma sink and I don't save it for an afterlife.
Re:Don't like man pages. (Score:4, Interesting)
Manpages suck for the average programmer. You're above average (so I am) but lots of the people I work with struggle with manpages. They seriously lack examples.
And then there are the man pages that say "look in header file X for the rest", and of course the headerfiles don't contain comments. So you'll have to figure out on your own what "FBIOGET_VSCREENINFO" means. (The V stands for 'variable', which google could tell me)
It's called engineering (Score:5, Interesting)
The resolution to the documentation problem is simple. I use it on my projects and when I managed programmers, I made them do it. Unfortunately, it needs discipline--the difference between programming and engineering--which is in short supply in the FOSS community.
The resolution is that you write the relevant section of the user manual first, have the client review it for clarity and sanity, and then make the software do exactly what the manual says.
Pause to recover composure
What could I be thinking?!
Not just beginner to apprentice. (Score:5, Interesting)
I've been a Linux user since 1993 and the state of Linux documentation today is worse than ever before if you don't happen to be an actual coder on a specific project reading project documentation for it in order to facilitate your work and contributions.
Back in the day, there were manpages, info pages, comprehensive documentation at /usr/doc or /usr/share doc for specific packages, and documentation files in nearly every source directory that you compiled yourself. You could also pick up just about any book on UNIX (System V Bible for SysV-like distros, or various BSD books) and apply much of what was said to Linux as well.
Everything was well-understood and common to the general state of things in the UNIX world and if you didn't understand something, a quick apropos/man or info or visit to /usr/doc or /usr/share/doc would result in enlightenment.
I'm a Red Hat/Fedora user since Red Hat 4 (Slackware before that) and as a 25-year UNIX veteran, I often feel like I have no idea what's going on in (for example) the init process, X configuration, desktop management, app resources/configuration, etc. Where are the dotfiles located? Where are the /etc components? What are the command-line arguments? Where are the manual pages? What documentation does exist is generally in the awful "Help Tool" format (click Help -> Help Contents in an application window and get a lot of prose for beginners). This documentation typically offers NO INFORMATION beyond the navigation of the user interface for the application. Nothing on system resources, locations of configuration files, dependencies, APIs, command line arguments, or anything that would allow you to either troubleshoot or modularly re-use the software item in question.
The system-level stuff (PackageKit, PolicyKit, SELinux, Udev, HAL, Plymouth etc. etc.) does not offer any clear location for configuration and typing for example "man selinux" brings up a couple of paragraphs with no detail. It refers to a pile of other manual pages, none of them installed by default. There is no overview. And SELinux is probably the most transparent of all of these.
The desktop is completely unmanageable if something breaks; the dotfiles are not in any concise location. gconf-editor is not installed by default and even after you do install it, there's no documentation on the options that it contains. It's not clear how to cause a command to execute on startup. You can go to GNOME startup options in a menu through which you have to use a GUI program to "add" things to the startup process, but the environment that's being configured for the processes spawned this way is not documented and many attempts to execute commands using this method fail.
More and more it seems as though I am constantly using find and grep either in all dotfiles in a directory or as root through the entire /etc, /usr/share, and /usr/lib directories to identify through keywords or binary strings either binaries or text files relevant to tasks I want to accomplish, then paging through them or opening the binaries up in a hex editor to try to grok what I need to change through sheer intuition.
Yes, I suspect there is documentation "out there" somewhere, but spending an hour trying to Google where it is located in each instance is an hour that I already don't have and that now can't go toward actually reading and grokking the documentation in question. But it appears to be just too much to provide easy directions to the technical documentation that exists, if it exists, in each case.
There is a definite ethos of "try to hide the system from the user" that has emerged in Linux and it does not make me happy, as is obvious here. I now spend several days each Fedora upgrade trying to bang my personal system into the shape I want it to be in. It used to be really simple to upgrade, and it was one of the greatest things about Linux. Just tr
Re:Yes it is terrible! (Score:3, Interesting)
My experiences (plural) with Ubuntu, MythTV, and MythBuntu (which was supposed to "streamline" the whole process) were similar in trying to set up a DVR.
Consumer-level HDTV card (ATi HDTV Wonder, PCI). ATi video board. ATi Remote Wonder II for my remote control.
Every time a new version of Ubuntu/MythTV/Mythbuntu would come out, I'd try to load it up and get it to work correctly. Multiple people insisting it would work fine, others insisting "no support" for the stuff. Back and forth. Most of the problem stems from the fact that in every stinking version, something gets changed, then it takes them a year or more to document the crap.
In the Ubuntu Hardy Heron attempt, every bit of documentation was either Gutsy Gibbon or Feisty Fawn. No help there. Tried again at Jaunty Jackalope's release WITH Hardy Heron, and still 90% of the damn documentation hadn't been updated. I'm stuck chasing around tidbits and forum posts with "well here's how you do it, LINK" only to find out that the link is either (A) for a version I'm not running, (B) assumes information I don't have, or (C) no longer available.
Tracking down how to set up a remote control reliably with Lirc is a pain beyond torture as well. I spend 99% of my time on Windows (hey, I have better things to do with my time than fight a damn OS. Windows does what I need it to do and runs what I want to run.) This is the "tutorial" for setting my remote control up under MythTV [mythtv.org]. And let me tell you right now, this thing is a shambles.
Linux people don't write clear-cut instructions for anything. This is true and I agree, it is Linux Bug #1.
From the server side of things... (Score:4, Interesting)
From the server side of things, yes I use google for Linux and other OSS software info. But I find that much more reliable than some of the 'enterprise' software companies and their documentation (Sungard & Blackboard among the worst in my opinion).
Even worse is the fact that many of these enterprise software companies have their documentation & support information protected by login so you are unable to search them with google (and their own internal search software is god awful).
Bad documentation is not an open source/linux thing. Its pretty much everywhere.
Re:Documentation is very lacking (Score:5, Interesting)
Oh, and Apple's documentation: HA! Sun writes some nice docs, though.
Re:Well, No Shit (Score:3, Interesting)
FreeBSD is indeed outstanding in the documentation area -- complete, thorough and consistent. And as an added bonus, most manpages are written to include examples and handholding (where applicable).
Linux, I'm afraid, suffers from, among other things, the man/info dilemma. Personally, I find info somewhere between retarded and useless, but to the extent anyone relies on using info as it was originally conceived, they'll discover soon enough that the info referenced in the manpage was never written.
As a workaround for the shoddy quality of Linux documentation, what I do is one of the following: (a) install the FreeBSD manpages into my home directory; (b) use a script to dump the on-line version into my terminal; or (c) simply write my own. Granted the FreeBSD manpages won't necessarily match up, but they're generally close enough to be adequate, and especially useful for unfamiliar concepts or commands.
As for writing one's own manpages, that does take a bit of knowledge, but it's far simpler than it appears. An alternative is to use Perl's immensely-readable and easy-to-learn POD format. Running 'perldoc /path/to/mypod' (or simply 'pod2man') gives you the same bold, overstriking and other formatting you'd typically expect from a manpage. Either way, writing your own seems to be increasingly necessary. Took me a while to document Firefox correctly, but I haven't had to waste any time since bouncing around dozens of Firefox sites to lookup the meaning of about:config settings. If you've got documentation, Google is *never* faster.
Manpages ideally should contain examples, but they shouldn't take the form of a tutorial. The web is littered with tutorials, so finding one is easy enough.
Re:And good luck with Google, too (Score:2, Interesting)
I'll say something else that's needed (Score:4, Interesting)
Coming at this from the perspective of a professional Linux sysadmin with quite a few years experience, I find a lot of forums downright painful.
Not because they're difficult to use or search - Google does a perfectly good job of indexing them - but because they are frequently a case of the blind leading the blind. I really have lost count of the number of times I've looked on Google to solve a problem, found a few forums and discovered two things:
1. I'm at a much more advanced point in the process than the OP. (Not really a problem, more an annoyance) /.'s moderation system. In an ideal world Google could pick up on this and show helpful replies above unhelpful ones.
2. The answers given are downright wrong, and demonstrate clearly that the person writing the answers has no understanding of what it is they're talking about. Which I wouldn't know were it not for (1), above. The forum software itself needs some way to mark replies as "helpful" or "unhelpful", much like
Mailing lists for the specific thing you're having trouble with tend to be better - largely because the barrier to entry for posting on a mailing list is rather higher.
apropos burn (Score:3, Interesting)
You've actually hit on one of the few examples that "sort of" works still in Linux (though it could be better).
On Fedora 12:
$ apropos burn
brasero (1) - Simple and easy to use CD/DVD burning application for the Gnome Desktop
$ man brasero
If only it actually worked this way (as it used to) for most of the rest of the Linux applications/tasks ecosystem.
Re:Yes it is terrible! (Score:3, Interesting)
Until Grandma or Grandpa can blindly install something without understanding exactly what they’re doing, Linux on the desktop will not be practical.
“Install this” is all the understanding your average user wants to have of the actual installation process.
Re:Documentation is very lacking (Score:2, Interesting)
I call BS. Go to Google and try searching for "burn a cd" and "burn cd." The results are pretty similar because decent search engines do more than simple text parsing and regular expression matching. As long as the vast majority of people continue to use Google, Bing, Yahoo, etc., they will come to expect that the search tool is actually trying to be helpful.
As an academic researcher, I regularly copy and paste the title of a paper that I am looking for into Google. When I do that, I also find similar papers on the same topic because their titles share words with the original title. This is very helpful. If "basic search technique" required me to get rid of "a," "an," "the," etc., my job would be a whole lot more frustrating.
Active v. Passive (Score:3, Interesting)
Facts:
- Yes, documentation sucks. This is because there are very few people who are both knowledgeable about what "the code" (meaning currently packaged distributions; bleeding edge stuff is a different kettle of monkeys) does and also like writing documentation. (Put aside being good at tech writing for the time being.)
- Things constantly change. As an example, Ubuntu's 6 month window leaves non-techy people breathless at the rapid rate of change, but at least it sets expectations. The tech publishing industry simply isn't capable, right now, of releasing books that fast, even if you assume the can opener of someone competent, willing, and able to write a book targeting the next release. I'm as quick to joke about M$ or Apple's release schedule, but the Missing Manual types at least have a target to hang a book release cycle on.
- Googlicous search is hit or miss, and humans have a cognitive bias emphasizing miss. The seven times you find exactly what you need to know (score!) are mentally outweighed by the one time you couldn't get your new video card to work.
Which all leads me to: the best way to run Linux is to be involved in the community. Folks in the know are much more willing to help you on a message board, IRC or whatever than to spend a week or six writing documentation. The payoff is much greater: someone happy at your interactive investment of two hours of partial attention. Contrast with the investment of a couple of weeks writing docs to see email from someone with weird hardware and poor attention to detail flaming you for "causing" them to lose their term paper.
Not everyone who wishes to run Linux wants to engage geeks on IRC. There is a mismatch there. But I don't see that changing.
There may well be an opportunity emerging for knowledgeable communicators - a $10 service targeted at narrow niches for people like my grandmother's new boyfriend - a non-geek who runs Ubuntu and manages his own website, but is generally clueless about what to do in the face of a problem. The niche is narrow; it has to target the impedance between wanting a fix now and waiting for me to be able to provide family tech support, and it has to actually work for his particular problem. And I think it looks more like tech support than publishing. Anyone who's read Rainbow's End by Vernor Vinge might see the model of 411 service here.
Re:Documentation Doesn't Matter.. (Score:2, Interesting)
Look, I know we like to joke around about it in computer circles, but computers are not toaster, nor are they microwaves. If someone's regarding it as something other than what it is (such as an appliance), then whose responsible for the fact that it doesn't work they way they expect?
At the risk of running counter to the Ubunutu philosphy, Linux isn't for everybody. That's why you don't just go to Walmart and pick up a Linux PC (oops...nevermind. [slashdot.org]). It's a hard lesson to learn: I'll be the first to admit that when I started with Linux I was a typical overzealous evangelist, constantly telling my dad all the reasons he should switch to Linux. It wasn't till one day when he saw me working in a full screen text terminal and said "Uh-oh, looks like you crashed!" that I realized it would be completely inappropriate for him to switch to Linux.
From it's humble Finnish beginnings, Linux has always been one thing: an operating system for the people who built it. The rest of us are opportunists.
Re:Of course it is. (Score:3, Interesting)
Well, back in the day, it would've been 'man cdrecord', which kind of makes sense. I honestly don't remember how I learned about cdrecord, or how I now know it's been renamed to wodim.
In all honesty, I suspect us Linux users have some sort of telepathic network...
However, trying some of the other questions gives some useful responses:
gives me k3b. Knowing that it's a KDE program, I might then look in the menus to see if it's a GUI program. It is, so I'm done.
houghi points the way to another possible answer. Personally, I'd Google for linux burn cd commandline [google.com] -- the tutorials returned are out of date, but still work. 'man cdrecord' doesn't give me anything, but 'which cdrecord' tells me it exists, and 'ls -lh `which cdrecord`' tells me it's wodim. So, 'man wodim' gives me the most relevant, though least userfriendly, documentation.
Note, none of this is at the expense of the fact that when I pop in a blank CD, I do get a GUI popup that lets me point-and-click to burn a CD. Since I'm on KDE, this probably leads to k3b, though I haven't used it in awhile.
Is Windows any better? What's wrong with Google? (Score:3, Interesting)
Ok, so I'll be the first to agree that Linux documentation is on the whole terrible. You can get some documentation with man, but unless you're pretty comfortable with a command line, the documentation is likely to be completely useless to the average user (I remember when I first started using Linux that figuring out how to make sense of man pages was often more challenging than just guessing how to do things). The contextual help in Ubuntu is slightly more readable, but usually useless when there's any available at all.
That said, is Windows documentation any better? I haven't really used Windows in a couple years now, but from what I recall, opening up one of the help files to figure out how to get something done was completely useless. I have generally found that I'm much more able to figure out how the program works by fiddling than by reading help pages. Less technical users (like my parents) generally can't figure out how to do things, it's true, but they also are completely incapable of finding the relevant help page - I suspect that the skills are related. I suppose what I'm trying to say is that for most end user applications documentation is pretty well irrelevant, and the real question is how intuitive the interface is. On this front I think that Windows and Linux are pretty well tied at this point, both lagging a ways behind the top to bottom uniformity you get from Mac OS.
Finally, is there really any problem with using Google as your documentation? I think that Google is the best sort available documentation on all the major OSes, and I'm not really sure I see the problem the summary is claiming exists. So, in summary, poor documentation isn't a linux problem, and I'm not even really sure it's a problem at all. This seems like a lot of fuss over nothing to me.