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?"

Comments

Of course it is.

[Mongoose Disciple]

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.

Re:Of course it is.

[Penguinisto]

True - though something is lacking in TFA: there is a diff between hitting the docs for learning, and hitting them for troubleshooting.

The man pages are more for learning (you can troubleshoot with them too, but diagnostic info in them are going to be lacking, just like trying to rely on the Windows Help files to fix a busted Exchange connector). Odds are, a beginner/apprentice won't know what to do with 'em for fixing a problem unless he/she is a royal badass at general computing/programming practices.

For troubleshooting, you're gonna have to hit Google - you have better odds there that someone else had the same problem and posted it (and its solution). There was once a time when you could write up docs for troubleshooting and diagnostics, covering up to 80% or more of what most folks run up against.

It still boils down to upping your skills on the OS and on general practices, though.

Re:Of course it is.

[Goaway]

Ok, I want to burn a CD, what "man command" should I use?

Re:Of course it is.

[prgrmr]

man microwave

Re:Of course it is.

[ls671]

> You've lost me already. I'm having to look up what "man" does.

try:
man man

Re:Of course it is.

[eln]

man pages are written by techs for techs, and are intended more as a reference than as a how to. They're very useful for people who are already familiar with Linux and just need to know the syntax for particular commands, but are not particularly helpful for people just getting into Linux.

Most of the previous attempts to create beginner documentation for Linux and other Open Source projects have suffered from the same basic problems:

1.) Nobody likes writing documentations. Technical people in particular hate writing documentation. It's tedious, boring, and generally unrewarding work. So, documentation tends to be sparse at best.
2.) The people who do bite the bullet and decide to write some documentation misunderstand their audience. They write at their own level, and make it easy for themselves, and perhaps their other technically-minded peers, to understand. Documentation is either very sparse, assuming a level of background knowledge that doesn't exist among beginners, or extremely precise, dense, and difficult to understand.
3.) Nobody reads the documentation anyway. People hate reading documentation almost as much as they hate writing it. When's the last time you bought something and actually read the manual that came with it? Reading documentation is boring and tedious, especially when most of it is so poorly written. People would rather tinker, then ask someone else for help when they break something, rather than slogging through documentation.

The basic result of this is we have two alternating types of stories on a semi-annual basis on Slashdot: Stories about someone trying to start a new Linux documentation effort, and stories about how much Linux documentation sucks. Meanwhile, the state of Linux documentation stays essentially the same: a mix of outdated and difficult to follow documents interspersed with large gaps where no documentation exists at all.

Re:Of course it is.

[gr8_phk]

I just put in a blank CD. Then a folder appears on the desktop with a button to burn the CD. I drag the file I want into there and hit that button. I'm not sure what this MAN thing is everyone keeps talking about.

Re:Of course it is.

[Anonymous Coward]

Worse, it's responses like the GP's that compounds the problem.

Noob: I don't know how to use Linux! Won't someone help me?
BOFH: *grumble*grumble* Look, here's the "man" command, dumbass. It obviously means "MANual". Get it? Figured you looked too stupid to figure out how to use Linux...
Noob: Um... when I type that, all I get is "What manual page do you want?" How do-
BOFH: Why you rotten little... just how stupid ARE you? Were you born and raised with Windows or something? You type in the command, kernel function, or standard library call in after "man", just like we've done for the past TWENTY FUCKING YEARS OF UNIX. Hello? Have you been paying ANY attention at all, you worthless little Windows runt? If I hear you badmouthing one of the most hallowed and revered of Unix commands again, I'll-
Noob: So... er... what man command do I use to learn how to burn a CD?
BOFH: (eyes starting to turn red, veins now starting to pop out of head, teeth clenching almost to the point of shattering them by the pressure) You... were... asking... about... MANPAGES... YOU... STUPID... ASSHOLE! What the fuck is WRONG with you? You don't use man to burn a CD! Where the hell were you raised? In Redmond? I bet you don't even know what revision of the CD filesystem to use to optimize storage and retain symlinks! As everyone ALREADY KNOWS, ASSHAT, you have to build up an ISO image from on-filesystem objects using the proper options for your image of choice, make sure the appropriate kernel options are compiled in (or, of course, make and install the proper modules via modprobe or insmod, or via the autoloading mechanism which ONLY the uneducated scum use because they don't know the glories of "pure" Linux from ten or so years ago, the stupid "modern" bastards), THEN you can "burn a CD", as you so quaintly put it! WHAT PART OF THIS IS NOT OBVIOUS TO YOU?!?
Noob: I...
BOFH: (starting to shake from pure rage) You're clearly too much of a moron to truly enjoy Linux! GET OUT! GET OUT OF MY SIGHT, WINDOWS USER! OUT! AND TAKE YOUR GODDAMNED "PRETTY" GUI WITH YOU!
Noob: Hey, guess what? In the time it took you to rant about all that, I got my CD burned under Windows and didn't have a raving insular lunatic insult me. And I was able to do it without having to study the history of an operating system. Sounds like I'm using Windows from now on.
BOFH: *sniff* Why don't people like Linux? We're so superior!

Yes it is terrible!

[InsaneProcessor]

This is one of the key reasons Linux is not mainstream for users (not us geeks but real users). The user does not want to learn how to do anything more on his computer than get is work done or enjoy the entertainment. User level documentation simple does not exist.

Re:Yes it is terrible!

[Americium]

Exactly. Creating documentation for mainstream users is completely pointless. I personally think Ubuntuforums has great docs. I can just copy paste what they tell me, and voila, i have fakeraid setup, or whatever else is hard to install.

Re:Yes it is terrible!

[FTWinston]

I had several issues and tasks that I wished to perform on an ubuntu install on my now-deceased old machine.

Some were easy to find, but some involved wading through page after page of contradictory forum advice, or advice that seemed to completely disable my network adaptor. Things that I had expected to be possible through a GUI required pasting invalid forum syntax into system-critical files, sometimes with unpleasant results.

I was using linux only because I had to (producing dedicated server binaries for a source mod server), and my task was pretty non-trivial for a first-time user. I really did try to enjoy the experience... but I found it largely cumbersome, and haven't been back. Which is a shame, tbh, cos I'd like to like it.

The main problem, for me, was that it felt like for every task I wanted to perform, I had to find an expert person on a forum who already knew precisely how to achieve said task. There was usually little possibility of the self-discovery that is generally possible with an intuitive GUI, in the areas where a GUI was lacking.

With hindsight, it would have been more efficient to have just paid an expert to produce the binary for me. Or better yet, to set up my environment the way I wanted it.

Re:Yes it is terrible!

[misexistentialist]

Sounds like Windows. Every time I need to set up a system it requires searching forums for registry hacks, third-party utilities, and info on "advanced" settings hidden by the gui to make even basic changes. Windows just has the advantage of annoying and frustrating a larger user-base who take to the internet to complain and find solutions.

Documentation is very lacking

[genkael]

As a linux user since 1995, I have found the documentation to be little more than it was around 2000. It's easier to do a google search than try to find an answer in a man page. Not only that, the man page rarely has useful examples, one of the biggest problems.

Re:Documentation is very lacking

[CasaDelGato]

The whole Linux Mindset to documentation can be summed up in the phrase "use the man page". Yeah, right. Man pages are only semi-useful if you ALREADY KNOW WHAT COMMAND YOU NEED. Trying to FIND the command to do something is nearly impossible. Almost as bad as trying to find out how to configure something. (just edit the twiddly.da config file in the googly.plex directory, note that the syntax is completely different from every other config file on the system.)

Re:Documentation is very lacking

[nomadic]

Well I've been using Linux since 1979, and the documentation has never been that great. I remember asking Linus and some of the other developers about it when I ran into them at Studio 54, but they were too stoned to answer. Man, it was crazy back then, you'd get high and write a program and you wouldn't even care about the documentation. You'd just copy over someone else's man pages, or paste in Beegees lyrics, or whatever you're drug-addled brain came up with at the time.

Re:Documentation is very lacking

[raddan]

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.

Don't like man pages.

[theNetImp]

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:Don't like man pages.

[dkf]

Manpages suck for the average programmer.

No. Most manpages suck, especially on Linux. Sorry, but it's true. BSD manpages are usually better because they've a legacy of being better (there's a history of them having had a good tech writer spruce them up sometime way back, and that's encouraged them to stay good) whereas too many Linux utils and syscalls are poorly documented (GNU utils because they think you should be using texinfo, Linux syscalls because there's a tendency to say RTFS).

They could be better. Making them better needs effort, and it needs someone other than the original developer to help (because the developer is usually too close to understand what needs to be documented, or at least that's how it is for me). I also advise not worrying about the format of the documentation; plain old text is hugely better than nothing...

And good luck with Google, too

[edraven]

As often as not, the only hits you get are posts in forums where someone is asking the exact same question you need answered... and getting no replies. Since 2005.

Re:Documentation lacking?

[L4t3r4lu5]

Wireless Howto

Wireless Howto
Roberto Arcomano berto@fatamorgana.com
v1.6 - July 31, 2002

Well, No Shit

[bsDaemon]

That's because its really difficult to determine what's "Linux" when you're talking about Linux. What works on RHEL/CentOS won't necessarily work exactly the same on Fedora, and will probably be way different than on a Debian box.

Contrast this, however, to one of the BSDs, say FreeBSD, which I am the most familiar with. Let us take a look here: http://www.freebsd.org/docs.html. All of these documents ship with the OS, so if you don't have a network connection (for instance, you need the docs to help you set it up), then you have them there as well. The FreeBSD Handbook covers everything from installation to configuring BGP.

There is a separate Developer's Handbook (which even contains a primer on x86 asm), a Porter's Handbook, etc. The docs that ship with the OS include even The Design and Implementation of the 4.4BSD Operating System, which is somewhat dated at this time, but still a great help in theory.

Then, of course, there are the man pages that everyone always mentions, which are awesome, but don't really help make the point I'm putting forward. Of course, the fact that FreeBSD can ship such thorough documentation is because FreeBSD is FreeBSD anywhere, where "Linux" is not. So, perhaps the problem isn't with "Linux," but with certain distributions not taking documentation seriously enough for the various common tasks and interfaces.

What I'm really getting at is, I should not have to Google around for random blogs and wikis to find out how to do a common task that I may be getting to for the first time, hope that I can find an answer, and that the source can be trusted. Any of the distributions which have any sort of commercial or foundation backing at all, really should just bite the bullet and hire on a few technical writers to actually make proper documentation, and then keep it up-to-date. Hell, even Microsoft updates their online help files, and most tasks in Windows are straight forward enough that only 4th grades and 60 year olds need to ask about it.

Relying on GUI config tools, DHCP, and other magic to keep "newbies" from needing to actually learn anything is counter-productive and isn't going to help create new professionals. "RTFM" shouldn't be a put down or a dirty word, but TFM needs to actually contain TFInformation. Is that really so much to provide?

It's called engineering

[thethibs]

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.

[aussersterne]

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

Random Online Linux Doc Complaints

[happy_place]

My beefs with Unix docs:

1. Forums that are simply copies of other forums with no actual contributions.

2. Installation documentation as the only source for certain unix tools. I don't know how many times I've found Redhat's website insufficient, because it's about how to do an initial install.

3. Too many man pages lack useful examples of how commands options are used and their output. (How hard is it to simply create a few examples?)

4. Invariably someone has asked the question I want answered online, but often that's it. There's no posted answer for the question in many forums/newsgroups--the thread's just left dangling.

5. Stale links and really old revisions of a program clutter/obfuscate searching for solutions.

Documentation Doesn't Matter..

[Jahava]

One thing the tech crowd needs to understand: A non-technically-minded person will never want to learn how to use a computer. It's not a matter of ignorance or stupidity. It's simply that a computer is, for them, just another appliance, and while (to you and I) it is a fascinating appliance with limitless potential, it is (for non-technical folks) a tool to get something done.

Except it's a really horrible appliance.

Compare it to a Microwave. A Microwave is obvious - it heats up things. There are sometimes lots of buttons, but they're not scary, and if something happens that you don't like, there's a big read "Cancel" button sitting right there. So you're not afraid to play around with it. You'll hit some buttons until it does what you want, and then you'll always hit those same buttons because you know they work. Every time you hit those buttons, your food gets warm in exactly the same manner.

Compare this to a computer. They take time to boot (that's not useful!) and crash. Moreso, when they crash, it's usually not fixed by just unplugging. If you push the wrong buttons on a computer, stuff breaks, and more often than not when stuff on a computer breaks, you can't solve it quickly. Best case you have to wait for it to boot again (it's not doing anything!) and worst-case you have to take it into a repair guy.

Even assuming things don't break, per se, look at all that can go wrong. A Microwave will never try to attack you, but if I miss one button my computer becomes hostile! On a computer I have so many options ... where to save a file? Who knows? I just want to put it somewhere and open it later. Organize? That's hard! What's a directory? Did I put it in "Pictures" or "Documents"? Or is it a Program File? I don't get it.

Now, my Microwave could have a dial on it that lets me control the fan speed. Another dial lets me control the microwave emitter's intensity. I could flip a switch and tune these dials just right, and cook my food just right. Cool! Or I could irradiate things lethally (or not, but it's a metaphor; suspend your imagination a little!) In fact, it's the very lack of options that makes the Microwave useful. I wouldn't judge a person for being too scared to change those dials, nor would I expect everyone to learn how.

To non-technical people, computers must be appliances, and they will prefer the OS and Software Suite that accomplishes this best. Right now that's Windows and Mac. Linux has too many dials. Things can go wrong. The end user cannot have anything go wrong ever. If you want Linux to reach the end-user, Linux has to be a better appliance than Windows or Mac. Some distros are better than others, but there are still way too many degrees of freedom. Software update sites, administrator accounts, audio not working, suspend issues, complex filesystems....

There are answers online for all of these questions. There is documentation for some, forums for others, and wikis for most. However, they all ignore the fact that these are problems that can not exist in a compelling appliance. Adding more documentation will make my job easier, but it will do nothing for a non-technical user.

Personally, the best appliance of all is looking like Chrome OS. And it's Linux!

I have 3 real issues with manpages

[AlgorithMan]

although I like manpages and do consult them, I prefer googling stuff, because three problems you often have are

• no examples
• the parameters are sorted alphabetically - so you might have to scroll through 50 screenpages of obscure parameters that you most certainly never need until you find the one you're looking for (IF you are still reading at that point)
• bad descriptions like --fluxcompensator activates fluxcompensation

just put some real-world examples at the beginning of the manpage and you're good...