Slashdot Mirror
Is Linux Documentation Lacking?
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?"
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.
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...
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?!
I'm a Programmer. That's one level above Software Engineer and one level below Engineer.
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
STOP . AMERICA . NOW
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.
Seconded. Anyone whose ever used a BSD system can attest to the quality of the documentation. I think the reason for this is that BSD devs are often required to submit documentation with their patches. The more decentralized Linux development model tends to overlook this. It drives me nuts; fortunately, most of BSD userland and Linux userland are the same, so I can refer to BSD docs for Linux stuff. Don't try to use BSD docs for GNU make, though. Oh, and don't get me started on Info pages. WTF.
Oh, and Apple's documentation: HA! Sun writes some nice docs, though.
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.