Forgot your password?
Open Source Programming Linux

Is Linux Documentation Lacking? 769

Posted by CmdrTaco
from the hackers-and-english-don't-always-mix dept.
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?"
This discussion has been archived. No new comments can be posted.

Is Linux Documentation Lacking?

Comments Filter:
  • by InsaneProcessor (869563) on Thursday December 03, 2009 @11:22AM (#30310480)
    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.
  • by mario_grgic (515333) on Thursday December 03, 2009 @11:22AM (#30310490)

    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.

  • by genkael (102983) on Thursday December 03, 2009 @11:22AM (#30310494)

    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.

  • by edraven (45764) on Thursday December 03, 2009 @11:24AM (#30310528)

    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.

  • by Anonymous Coward on Thursday December 03, 2009 @11:28AM (#30310592)

    Compare the Linux documentation to the FreeBSD Handbook and you will see that Linux has no documentation to speak of. Perhaps that's the price you pay for having no central management, I don't know.

    Oh, and can we please get rid of that awful Gnu Info crap?

  • Yes. (Score:4, Insightful)

    by LWATCDR (28044) on Thursday December 03, 2009 @11:29AM (#30310602) Homepage Journal

    Writing documentation is hard work and is boring. It is also thankless.
    The funny thing is that documentation for the most technical programs tends to be very good. PHP, Perl, Apache, Postgres, and MySql all do seem to have good documentation.
    Gnome not so much. Many other apps also seem to lack good docs. X is just a disaster. It is documented but it is still a pain when things fail they are a huge mess to fix.

  • Yes (Score:2, Insightful)

    by DontBlameCanada (1325547) on Thursday December 03, 2009 @11:29AM (#30310604)

    In a word, yes, many/most linux docs suck.

    Man is useful once you understand the basics of how a command works. However, if you're sufficiently green, decoding the language in many of the man pages is difficult. When executing certain system management tasks as root, a mistake can be catastrophic. Google will pull up the man page for you, but also the infinitely more educational blog and faq pages that decribe what a command does, when you use it and how to trouble shoot problems encountered with it.

    The problem with Google, is the non-official blogs and faqs frequently reference older version of the command line tools bundled in the latest distros. Occasionally, the tool author radically alters the tools between releases rendering the non-official docs inaccurate... Then the neophyte/newbie hobbyist is up the creek with a paddle.

  • by Dr_Barnowl (709838) on Thursday December 03, 2009 @11:31AM (#30310642)

    Getting the detail you want out of a man page is often harder than finding the relevant bits on Google. And of course, man pages don't help you at all if you don't know which command you want to be using ; and let's face it, for a given task, there might be three ways of doing it.

    I'm still a relative Linux novice despite having used it for some time now, but I'm a programmer and prepared to slog through documentation and web pages to get things going.

    Example - the prune argument of find. I'll give a limited-edition photon to the first person who figures out the way to use the prune argument to produce a list of files that _doesn't_ match a particular path pattern, solely limiting themselves to the man page, without using Google.

    find . -path '*/not-these' -prune # This does basically the opposite of what you'd expect it to.

    Yes, I know how to do it NOW. Well, Google remembers which page I found most relevant for the search terms that eventually found the right way.

  • by Americium (1343605) on Thursday December 03, 2009 @11:34AM (#30310672)
    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.
  • Well, No Shit (Score:5, Insightful)

    by bsDaemon (87307) on Thursday December 03, 2009 @11:35AM (#30310678)
    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: 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?
  • by Anonymous Coward on Thursday December 03, 2009 @11:36AM (#30310692)

    Perhaps that's because you have only seen Linux (or Gnu) manpages. Take a look at the (Free-)BSD manpages and you will be pleasantly surprised.

  • by FTWinston (1332785) on Thursday December 03, 2009 @11:40AM (#30310762) Homepage
    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.
  • by mark-t (151149) <[markt] [at] []> on Thursday December 03, 2009 @11:41AM (#30310780) Journal
    Nope. Most users don't bother to even *READ* documentation, so the lack of it would not be a factor.
  • by Goaway (82658) on Thursday December 03, 2009 @11:45AM (#30310848) Homepage

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

  • by godrik (1287354) on Thursday December 03, 2009 @11:46AM (#30310850)

    And you are exposed to none compatible solutions. The number of doc out there that still use insmod/rmmod instead of modprobe is high. The number of solutions that tell to install software manually instead of using the one from your distro repository is high. Google is good to get a basic understanding of the concept and problem. Then read the manual (not only talking about man pages)

  • by jellomizer (103300) on Thursday December 03, 2009 @11:49AM (#30310906)

    You make it sound like a bad thing...

    Yes people don't want to tweak config files to give it an extra 10% speed improvement. Or fuss around searching for "Pure" GNU drivers that work. They just want a system that boots up, allows them to go to their apps get their work done. When they are done with work they may want some entertainment out of the device.

    Do you feel you have to know how every component in your car works.
    All the technology and people who go is to flushing your toilet making sure that nasty stuff leaving your body doesn't come back to haunt you again.
    Do you need to know what materials your desk is made out of, how they cut the wood etc...

    There is a lot of stuff going on outside of our areas of interests. We use a lot of such products and services but don't even think about all the details that goes on, for the most part we don't care, even if it vitally important to us, but as long as it works we are happy.

  • by smooth wombat (796938) on Thursday December 03, 2009 @11:49AM (#30310910) Homepage Journal
    If someone makes a good piece of software, it'd be great if someone else came along to document it, and everybody wins.

    Here's an idea: how about the person who did the actual work do the documentation? That way, since they know all the ins and outs, someone else doesn't have to pester them to find out how to do something and document it.

    Yeah, yeah. That would be too easy and make sense. Let someone else take care of the problem because I'm too lazy.

    There is no reason in this day and age that the person/people creating these apps can't provide documentation at the same time. As others have already pointed out, until there is good documentation and yes, even a simple walk-through if it's warranted, it will NEVER be the year of Linux on the desktop.
  • Ironically, (Score:3, Insightful)

    by aussersterne (212916) on Thursday December 03, 2009 @11:49AM (#30310912) Homepage

    man pages used to be great. They used to absolutely rule and tell you exactly how to use any part of the system. Now, most things are lacking a man page entirely (man openoffice, man gnome, man kde, man evolution) and the man pages that do exist either tell you nothing or tell you nothing useful.

    And, even more ironically, there used to be dozens of desktop manpage viewers, most notably xman from the basic X applications toolset installed on all UNIX and Linux desktops with X. You could even type "man:command" into most Linux browsers and read the manpage. Now none of this exists; it has been TAKEN OUT under the theory that user access to documentation or utilities of this kind is bad for some reason.

  • by HockeyPuck (141947) on Thursday December 03, 2009 @11:51AM (#30310940)

    I would assume that the average user doesn't use the CLI. Whether in windows or linux, so why should we assume that the average user would even look at man pages. Man firefox? Man calc/writer/impress? Doubt it. Take openoffice for example... let's say I want to create a textbox, so I go to the landing help page for and I'm presented with 4 textboxes,

    -Complete Documentation Wiki
    -OOo FAQ on the Wiki
    -OOo Manuals on the Wiki
    -Documentation Website

    How is the avg user supposed to know which one to search in and the results are just a output of a google search. It would be nice if it provided more information or catagorized the output along the lines of tutorials/videos, manuals etc rather just whatever google spits out.

    And is one of the better sites.

  • by MpVpRb (1423381) on Thursday December 03, 2009 @11:54AM (#30310978)

    Man pages are great to remind you of the details, if you already know how something works.

    Man pages are terrible for learning something new for the first time.

  • by zwei2stein (782480) on Thursday December 03, 2009 @11:54AM (#30310982) Homepage

    I can top that:

    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. And that person is me.

  • by happy_place (632005) on Thursday December 03, 2009 @11:57AM (#30311024) Homepage

    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.

  • by Anonymous Coward on Thursday December 03, 2009 @12:00PM (#30311106)
    You're being a pedantic idiot. That's not what he meant and you know it.
  • Re:Yes. (Score:2, Insightful)

    by Vanderhoth (1582661) on Thursday December 03, 2009 @12:01PM (#30311108)

    If it wasn't well documented when it was being developed it falls on someone else to do it later. That someone has no real vested interest in documenting something they didn't write.

    I'm a developer and have had to deal with several legacy applications that contractors had previously written. When I first started my job I was pretty much given one of these applications and told it needed some documentation updating. I feel extremely annoyed when I look back and realize that for pretty much the first year of my job I was writing developer, security and user doc's for someone else poorly coded system. The result is the documentation I wrote for the other systems is probably incomplete or doesn't make perfect sense in the grand scheme. It seems a little arrogant, but I no longer accept responsibility for applications written by other people, epically contractors that were hired to write an application, which should have taken one to two years to develop, in six months. If someone insist I take over a project I tell them I want to see to documentation and code first if it's good I'll accept, if it's bad I'll accept on the condition I get to redevelop the whole project because it takes less time then writing, rewriting or expanding existing documentation while fumbling through someone else hacked together code.

    Sorry for the rant. I read this saying somewhere, "Document your code like the person who will maintain it after you is a psycho pathetic killer who knows where you live".

  • by Vanders (110092) on Thursday December 03, 2009 @12:11PM (#30311282) Homepage
    It's even worse if you do have GNU info installed and are naive to actually try to use it.

    GNU info needs to just die. Preferably in a horrible, painful fashion, with lots of screaming and blood.
  • Obligatory (Score:1, Insightful)

    by Anonymous Coward on Thursday December 03, 2009 @12:13PM (#30311324)
  • by Anonymous Coward on Thursday December 03, 2009 @12:15PM (#30311346)
    Let's be honest: Documentation of open source programs is generally TERRIBLE. Anything unusual you want to do usually requires a week of experimentation.
  • by ehntoo (1692256) on Thursday December 03, 2009 @12:17PM (#30311388)
    It's just horrifically out of date. If you're talking about Linux as in things that are generally applicable to all Linuxes, the Linux Documentation Project ( is actually quite well written... but almost everything is uselessly out of date. Most of the articles I've needed in desperate hours of trouble are still written for the 2.4 kernel series. This was especially painful when I was looking into software RAID. There's some great stuff in TLDP, but it's all outdated. At this point, I think gentoo-wiki and ArchLinux's wiki are some of the most helpful places to go if you're using anything that's not .deb or .rpm based.
  • by Anonymous Coward on Thursday December 03, 2009 @12:18PM (#30311398)

    The important things to have in mainstream-user documentation are, in this order:

    1. Have a UI that allows users to see everything that they can possibly do with the program

    2. Have on-hover tooltips that explain what everything does if it is not immediately clear

    3. Have few inconsistencies between how this program works and other programs work

    4. Have searchable, readable documents that wholly explain the program.

    For command-line programs, you don't get hover tooltips so users need --help, usage(), and man pages that explain what the program does, and the programs should run without side effects if the user decides to run them to see what they do.

    Good example:
    ~user$ xyzzy
    xyzzy [filename] -- frobnicate a file.

    Bad example:
    ~user$ xyzzy

    [hangs on input]

    Worse example:
    ~user$ xyzzy
    ~user$ ls ~

  • by eln (21727) on Thursday December 03, 2009 @12:19PM (#30311420) Homepage
    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.
  • by digitig (1056110) on Thursday December 03, 2009 @12:24PM (#30311508)

    Let's be honest: Documentation of open source programs is generally TERRIBLE. Anything unusual you want to do usually requires a week of experimentation.

    Absolutely agree, 100%. But it's worth adding that documentation of closed source programs is generally TERRIBLE too. I bet we all have some horror stories!

  • by Jahava (946858) on Thursday December 03, 2009 @12:24PM (#30311514)
    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!

  • by dkf (304284) <> on Thursday December 03, 2009 @12:36PM (#30311790) Homepage

    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...

  • by mpapet (761907) on Thursday December 03, 2009 @12:38PM (#30311832) Homepage

    One of the interminable flame wars when GIMP stories run is "If it just had feature XYZ... then I'd switch." Or, the flamebait, "GIMP isn't as good as Photoshop, therefore I'll never use it."

    In this case, "If only a Linux distro had more XYZ... then I'd switch." People are stubborn. They will either switch and deal with the learning curve (warts and all) or they won't and they'll start flamebait threads like, "Docs suck..."

    Like the GIMP, when some Photoshop feature makes it into the application, (ex. color management) the "If it just had feature XYZ..." comments don't decline and the new users don't come flooding in. Bottom line, there's no amount of documentation that would end the "Docs suck" post.

    Do some specific applications need better documentation? Sure, but that's not a Linux-specific problem. Overall, it's a very well documented OS.

    I don't know if anyone has mentioned the Gentoo pages, but those are pure gold when I don't know where to start.

  • Re:Ok then.. (Score:3, Insightful)

    by rubycodez (864176) on Thursday December 03, 2009 @12:40PM (#30311860)

    my Ubuntu 9.10 does that too. helpful when I plug in my usb camera too

  • by BrokenHalo (565198) on Thursday December 03, 2009 @12:42PM (#30311912)
    Openness implies access, understanding, knowledge, transparency. Without documentation, none of these exist.

    No, you're conflating two completely different things. Open (as far as software is concerned) refers to access to, and freedom to use and re-use code. Documentation is (regarded as) a boring task required to make code accessible for newbies. Sure, it would be nice if the programmer could do both, but the simple fact is that it is common for competent programmers to lack the requisite communication skills for writing useful documentation.
  • by lattyware (934246) <> on Thursday December 03, 2009 @12:44PM (#30311948) Homepage Journal
    Protip: Find the software you want, then turn to your package manager. If you have to compile stuff by hand and don't want to, you are not running a suitible distro.
  • by kimvette (919543) on Thursday December 03, 2009 @12:45PM (#30311966) Homepage Journal

    Standard responses to new user questions up to around 2005

    "man $foo"/"RTFM" (nice reply. This is why it was SOOOO hard for Linux to gain ANY traction in the first 15 years it existed.)

    "it's open source. Fix it yourself."

    "it's open source. Document it yourself." (Um, if they don't know how the app works, they can't document it)

    "Read the tutorials/howtos" (The tutorials/howtos might cover the very basics, but often don't even touch upon what the user is asking about. Even better is when the tutorial says "to be added later." Or, the howtos are written for sysadmin types by developers with asperger's syndrome, not written for typical users. They may a well have been written in hieroglyphics as far as end users are concerned)

  • by gobbo (567674) <(moc.liamg) (ta) (etirwerw)> on Thursday December 03, 2009 @12:45PM (#30311968) Journal

    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.

    The fascinating thing about man pages, for me, was how utterly obscure some of them are to beginners. Most of them assume an intermediate understanding of unixy concepts, and don't bother to explain the context of the command -- i.e. when and why you would want to use it in the first place!

    The whole experience of learning to use the command line reeked of disdain for those who hadn't been to school (or endless sexless nights in the basement) to study the stuff, and myopia about the fact that someone may be coming at all this from a different angle.

    Which I guess is just nerdly, right? what did I expect.

  • by misexistentialist (1537887) on Thursday December 03, 2009 @12:54PM (#30312144)
    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.
  • by Anonymous Coward on Thursday December 03, 2009 @01:00PM (#30312272)
    Grandma and Grandpa aren't going to be installing a fakeraid, sorry. As for just installing software, Ubuntu is much easier then Windows. You open up the Software Centre and then browse through the nicely categorized software. Installation is 1-click for most software (especially software granmda & pa would be using). This is in contrast to Windows; Google it, go to vendors page, search for download link, download, run exe (presumably after clicking through a few scary warning saying not to run software from untrusted sources), follow the wizard (which typically asks what type of install you want, etc.), finally get the software. This is rote procedure for most users, but grandma and pa would be lost.
  • by julian67 (1022593) on Thursday December 03, 2009 @01:14PM (#30312540)

    Because almost every application/tool is also found packaged for OS X, BSD, even for Windows....obvious likely exception: the Linux kernel docs. So the article is kind of stupid from that premise onwards. But anyway how about someone offer more than a single example, not just anecdotes, cliches and rants? While remembering tfa is about new(ish) users' experiences?

    Assuming a new(ish) user is using a graphical environment means that man pages will not be the first place a user looks. So basically we're looking at the docs specific to the environment (Gnome/Xfce/KDE etc) and the docs of the individual applications. Almost every gui application I've seen has a 'help' button on the menu bar. Some of these launch a help doc in a doc browser, some a locally hosted html doc in the default web browser and some do the evil thing of offering only a web address and assume you are connected...grrrr. Most of the apps I use have very decent help docs. A few don't have anything useful and then again some are models of excellence. I notice the same situation when I use Windows. It's really dumb to say this is some endemic problem with Linux/free software.

    If the issue is with stuff like 'how do I set up RAID' or 'how do I install with /home encrypted' then this is up to the distribution to get right. Some are better than others. In Debian there is the online Debian Reference, a reference guide aimed at *users* not developers. This can also be installed and so be accessible without a net connection. It covers all kinds of stuff from the introductory section on the UNIX filesystem hierarchy i.e. what are /etc /home /var and what is the root account, right through to setting up your own subversion repo or customising the kernel.

    Occasionally a user might come across an application which is poorly documented, that is there is little documentation or the documentation is inaccurate/outdated/difficult to understand. But why should one or two particular/anecdotal experiences lead to a belief that 'omg linx has bad docs!' It's an overreaction, but I suppose it fills column inches for bloggers/journos and offers the casual blowhard the opportunity for a badly informed whinge post on a board.

    Thinking back to the last thing I struggled with: wake on lan. I didn't have a clue what to do to set it up. Searched distro wiki for wake on lan, result being a page of good instructions about which tools to use, how to check my ethernet card supports it, how to enable it, a brief comparison of two different wol clients, lots of examples and other helpful stuff. A few minutes later had it all working. Shocking!

  • by Jason Earl (1894) on Thursday December 03, 2009 @01:16PM (#30312582) Homepage Journal

    Here's the thing. If you find yourself wanting to read the man pages, and you are confused by them. Go and purchase a copy of "Running Linux." Any edition will do. That's how most of us that *like* Linux learned to use it.

    For most users, however, the man pages are just a waste of time. The have no desire to learn to use the various command line flags for "tar," nor do they want to understand the vagaries of cat.

    For that matter, they don't want to learn how to create a partition for /home (which is the example used in the original article). The whole idea that the operating system should make this sort of activity accessible to newbies is simply ridiculous. By this standard Mac OSX is *more* difficult to use than Linux, and Windows is completely unusable.

    Ubuntu's auto-partitioner gets this absolutely right (while still giving people that want a separate home partition the tools they need).

  • by AlgorithMan (937244) on Thursday December 03, 2009 @01:39PM (#30312976) Homepage
    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...

  • by SanityInAnarchy (655584) <> on Thursday December 03, 2009 @01:45PM (#30313096) Journal

    I can access help files with a mouse click, too, where it makes sense.

    For comparison, open up a Terminal in Mac OS X, and tell me what you find for documentation. In fact, I dare you -- try the same with start->run->cmd on Windows.

    If you're already in a commandline environment, man makes sense, and Google makes sense as a way to find out about man. I know of no OS which provides point-and-click help for the commandline, nor can I think of a sane way to do it.

  • by toadlife (301863) on Thursday December 03, 2009 @01:49PM (#30313150) Journal

    Documentation of open source programs is generally TERRIBLE.

    The FreeBSD handbook being a notable exception.


  • by Tubal-Cain (1289912) on Thursday December 03, 2009 @02:29PM (#30313842) Journal
    On Windows the question the users ask isn't "How can I do this?" but rather "What do I have to buy that will do this?"
  • by tjstork (137384) <todd DOT bandrowsky AT gmail DOT com> on Thursday December 03, 2009 @02:32PM (#30313878) Homepage Journal

    And how the hell is some user sitting alone in his room soupposed to know this? Perhaps if there was a "readmefirst" file on the desktop to give new users this info, but there isn't.

    The larger point is that the user cannot do this at all with Windows. How do you mind out what an exe in your process list does there? You Google it!

    In my mind, I would expect documentation for Windows to be far superior to that for Linux, because Microsoft can pay technical writers, as can most commercial publishers. But, they don't. Instead, they ship the minimum docs they can and then sell books through MS Press. What's really the difference between that and buying a book through O'Reilly? Not much.

    Bottom line is, the whole "Linux has no documentation" argument is a strawman, and I know what strawmen are, because, I myself have made enough of them to feed a thousand cows, for sure. Linux has rough documentation, but so does -everything- else.

  • by gobbo (567674) <(moc.liamg) (ta) (etirwerw)> on Thursday December 03, 2009 @03:01PM (#30314278) Journal

    oh, don't get me started.... ALL OS's suck, they just incite different kinds of violent feelings!

    MS has always had a central figurehead to vent spleen upon. Linux just gives one a feeling of antipathy towards nerd-dom... unless it's the urge to revenge that comes from a particularly bad man page.

  • Re:Ok then.. (Score:3, Insightful)

    by IICV (652597) on Thursday December 03, 2009 @03:09PM (#30314418)
    And if you tell that dialog "I want to burn these files to the CD", you'll get a CD that only works on other Windows computers. By default, Windows does not burn CDs in a manner compatible with anything but Windows. That's so much more user friendly than Linux or OSX, because everyone loves the mystery of "why doesn't this CD work on my friend's mac?"
  • by Rufty (37223) on Thursday December 03, 2009 @03:20PM (#30314578) Homepage
    $ man ls
    SEE ALSO The full documentation for ls is maintained as a Texinfo manual. If the info and ls programs are properly installed at your site, the command info coreutils ’ls invocation’ should give you access to the complete manual.

    And now we're into a whole new world or "how the hell do I quit this???" Can info just die now, please?
  • by SanityInAnarchy (655584) <> on Thursday December 03, 2009 @03:25PM (#30314648) Journal

    That's a bit like saying, if you need to write a program, someone has failed.

    Now, if you need to be in the commandline to do something which an ordinary user should be able to do, for which there is a sane GUI equivalent, I agree -- that shouldn't happen.

    However, there are and always will be things which are easier to do with a commandline, and things which can't really be expressed elsewhere. The use of pipes alone warrants that.

    A fun example would be taking a disk image, checksumming it while compressing it lightly and sending it through an encrypted tunnel to a server, as with light enough encryption, this will actually be faster than sending it unencrypted -- especially if the destination drive is slower/busier than the source drive... then, when it's done, transfer the checksum to the server and have the server decompress the image while verifying the checksum, then immediately re-compressing it with much heavier compression, taking several hours...

    You could argue that specific parts of this could be done better -- maybe I should checksum the compressed file so I know sooner. Then again, my way means I'm also checking the compression itself -- it means I absolutely am getting out of the other end the same thing that was on disk. You could also argue that I should bundle all of this into a piece of GUI software designed for taking disk images -- debatable, but I can go with that.

    But the fact that I need the commandline to do that now isn't a bug, it's a missing feature. In this case, the commandline is almost acting as a kind of software development -- and it is, after all, Turing-complete.

    I'd argue that if you need a GUI for something, that's also a failure. GUIs aren't reliably or easily scriptable, and the concept of pipes doesn't really apply. The above procedure would work, if the GUI had been developed with it in mind -- but it'd have to be a very specific GUI, whereas on the commandline, the compression tools, checksum tools, imaging tools, and encrypted tunnel, are all completely independent and generic -- the same compression tool that I might use to unpack a tarball will also handle a disk image. The same imaging tool which could create a file on an external hard drive can also stream the image over the Internet -- all without knowing anything at all about either of them.

  • by aussersterne (212916) on Thursday December 03, 2009 @05:17PM (#30316298) Homepage

    Exactly. There was a moment (between Red Hat 9 and say Fedora 2 or 3, in Red Hat land) when the best of both worlds was present... You COULD use perfectly useful GUI tools to manage things and it was great for end users to have them at that level of functionality, but you COULD also still manage your system with an xterm and vi, adding things to the .xinitrc/.xsession process, using xset to manage power saving, compiling your own kernels and assuming that in most cases it would work with the userland and installing these kernels from a root shell.

    Now .xinitrc/.xsession are ignored unless you radically reconfigure things. The GNOME startup is (as you say) not only opaque but dispersed across hundreds of files not only in $HOME but also in /usr (just try to manage your menus without alacarte or change your icons in Do-Docky), the X resources system and classic arguments like -geometry are absolutely useless (you actually have to start apps one by one and hunt down configuration tools in order to affect their behavior).

    On top of that, when you compile a kernel, virtually every systemic option threatens to fail to work with your userland. You have to trudge through documentation to see whether or not virtually every other option is necessary for some subsystem, and if you fail, you will not boot (or will not manage to get to your desktop). On top of that, installing a kernel now involves initrd management and questions about whether parts of the userland depend on vendor extensions to the kernel.

    Yes, some of this is Red Hat, but it's also typical with ubuntu and SuSE, virtually all of the "leading" distributions.

    Those who say "just switch to Slackware" or "just switch to Debian" miss the fact that full current hardware support (which these days is more and more in the userland) requires these updated userlands.

    There is no essential reason why userlands these days have to ignore things like -geometry, -xrdb arguments (and the X Resource Database) .xinitrc/.xsession, etc.

    It's a philosophical shift toward a monolithic SYSTEM (like Windows) and away from Unix modularity. People used to complain about the monolithic KERNEL. Now dispersed parts of the installation across all of userland are critical. There is virtually no modularity left in the most recent distros.

    It's a shame, because I think the parallel mode of thinking (we'll honor old UNIX standards *and* build new user-friendly tools around them) was a much better way to go.

  • by Matheus (586080) on Thursday December 03, 2009 @08:02PM (#30318838) Homepage

    I completely disagree. The person who created the application needs to be able to somehow convey the technical details and functionality of said application: True.. BUT everybody has their talents and I've found time and time again that writing great documentation that is clear, consistent, easy to use and understandable by a wide variety of user is very much a talent and usually one the developer doesn't posses. Even if the developer happens to have this talent, they rarely have the proper perspective on the product to document it for a third-party. The best documentation creator is someone with the talents to produce the document and direct access to the developer for the nitty-gritty specifics. They can then document the use of the program from a closer perspective to a outside new user because they at the start are that person BUT they have the access to the developer to fill out the documentation with the details that aren't readily apparent using the app.

    This could be a great business model:
    Customer: The people, companies, open source communities developing products / solutions.
    Business: A group of talented documentors who work with these groups to create quality documentation.

    Oh wait.. isn't that what O'Reilly is?

Never invest your money in anything that eats or needs repainting. -- Billy Rose