Please create an account to participate in the Slashdot moderation system


Forgot your password?
Open Source Programming Linux

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?"
This discussion has been archived. No new comments can be posted.

Is Linux Documentation Lacking?

Comments Filter:
  • Of course it is. (Score:5, Interesting)

    by Mongoose Disciple ( 722373 ) on Thursday December 03, 2009 @11:21AM (#30310474)

    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: (Score:3, Informative)

      by ls671 ( 1122017 ) *

      > Of course it is.

      Agreed, first tip for the "beginner to apprentice":

      Learning to use the "man" command is important, remember that you sometime have to add a number parameter to get the documentation that you want to get ;-)

      • 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 prgrmr ( 568806 ) on Thursday December 03, 2009 @11:50AM (#30310926) Journal
          man microwave
        • Re: (Score:3, Funny)

          by houghi ( 78078 )

          You ask two differnt questions. The first is how to burn a CD. The second is what man command you could use. Using a man command will not burn the CD so has no relation to the first question.

          I assume that the first question is more urgent.

          Or you start here: []

        • by ls671 ( 1122017 ) * on Thursday December 03, 2009 @11:58AM (#30311046) Homepage

          man 1 cdrdao

        • by ais523 ( 1172701 ) <ais523(524\)(525)x)> on Thursday December 03, 2009 @12:20PM (#30311436)

          $ man -k burn cd
          brasero (1) - Simple and easy to use CD/DVD burning application for ...
          k3b (1) - KDE CD burning program

          There were more answers than those two, but either of the first two looks a sensible choice for burning CDs. (The results quickly drop off in quality, though; the fourth was the Perl module Language::INTERCAL::Charset::EBCDIC, which I strongly hope can't burn CDs...)

        • by gr8_phk ( 621180 ) on Thursday December 03, 2009 @12:28PM (#30311606)
          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.
        • 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: (Score:3, Informative)

          by mweather ( 1089505 )
          man apt-cache. That'll tell you how to search the repo for a CD burning program.
        • Re: (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:

          apropos burn

          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 po

      • by eln ( 21727 ) on Thursday December 03, 2009 @12:19PM (#30311420)
        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. (Score:5, Informative)

      by Penguinisto ( 415985 ) on Thursday December 03, 2009 @11:41AM (#30310778) Journal

      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: (Score:3, Insightful)

        by gobbo ( 567674 )

        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

        • Re: (Score:3, Insightful)

          by Jason Earl ( 1894 )

          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

  • 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 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.
    • 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 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.
      • Active v. Passive (Score:3, Interesting)

        by abulafia ( 7826 )
        I think this illustrates the key point about Linux documentation.


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

    • Re: (Score:3, Insightful)

      by mark-t ( 151149 )
      Nope. Most users don't bother to even *READ* documentation, so the lack of it would not be a factor.
    • Re: (Score:3, Insightful)

      by jellomizer ( 103300 )

      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 nast

    • Re: (Score:3, Interesting)

      by Moryath ( 553296 )

      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 ste

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

    • Re: (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.

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

    • Not to mention the GNU apps that have manpages that (at least on some Linux distros) basically say "Yeah, it's a piece of software, if you want more docs install the info package for it" which is completely unhelpful when you're on a system that barely boots and you can't install packages with the system in its current state.

      /Mikael (who recently installed a Linux distro for the first time in a while, FreeBSD just didn't want to play with the netbook)

      • Not to mention the GNU apps that have manpages that (at least on some Linux distros) basically say "Yeah, it's a piece of software, if you want more docs install the info package for it" which is completely unhelpful when you're on a system that barely boots and you can't install packages with the system in its current state.

        I've been there... not in a long, long time... but it left deep wounds.

        Similarly, try setting up any new machine with any operating system these days without an internet connection... or with an exotic wireless card. How will ordinary mortals survive the 21st century? Let's face it, most of the planet can't tell a mac address from a big mac.

      • Re: (Score:3, Insightful)

        by Vanders ( 110092 )
        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.
        • Re: (Score:3, Informative)

          by ThePhilips ( 752041 )

          GNU info needs to just die


          The shell function makes "info" tad bit more usable to me:

          info() { /usr/bin/info --subnodes --output=- "$@" | $PAGER; }

    • Re: (Score:3, Insightful)

      by Anonymous Coward

      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?

    • Not to mention you need to know which man page to invoke which is *REAL* great for beginners.
      • Re: (Score:3, Informative)

        by Bluesman ( 104513 )

        >apropos [thing I want]

        But Linux distros could learn a lesson from FreeBSD in this regard. The FreeBSD docs are nothing short of excellent, and standard for the entire system.

        • by raddan ( 519638 ) * on Thursday December 03, 2009 @12:09PM (#30311266)
          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.
    • by CasaDelGato ( 701438 ) on Thursday December 03, 2009 @11:36AM (#30310698) Homepage
      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.)
    • by nomadic ( 141991 ) <nomadicworld@gmai l . c om> on Thursday December 03, 2009 @11:40AM (#30310766) Homepage
      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: (Score:3, Informative)

      by godrik ( 1287354 )

      Well, the man pages are only supposed to give the formal parameters of the command. The actual use of the command in a given context are given by HOW TOs.

  • by theNetImp ( 190602 ) on Thursday December 03, 2009 @11:23AM (#30310500)

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

    • RTFM (Score:3, Funny)

      by thijsh ( 910751 )
      Yeah, but don't even try to ask for any help, you'll most likely get an RTFM response. XKCD said it best: []

      I think it's safe to say the documentation isn't really lacking, but the support is... :)
    • 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.

  • Yes. Why not? Most commercial software ships without documentation too. If I want to figure out how to do something on Mac I google for it first. Similarly for Windows. When I was first starting out, Back In The Day (well, mid-90's) I bought "Running Linux" and "Linux in a Nutshell" (which, IIRC, was compiled from man pages) from O'Reilly, and read those rather than using man pages.

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

    • Re: (Score:3, Insightful)

      by godrik ( 1287354 )

      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)

    • Re: (Score:3, Insightful)

      by zwei2stein ( 782480 )

      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.

  • Yea, generally when I'm trying to figure something out, I'll do a search of the 'net for a quick answer and then reach for an O'Reilly (via Safari) or Addison-Wesley book for in-depth knowledge.

    The problem for me is that the man page is either a paragraph or two and not much help or 35 pages of incredibly detailed information that's difficult to parse. I'll do a google man page search at times just so I have an easy way to browse the page.

    A man page doesn't provide a tutorial and many times don't even provi

  • Contributing to the problem of finding good documentation is the fact that LUGs, distro companies, etc all mirror same crappy outdated collection of HOWTO's and man pages on their websites, and thus the newbie desperate to find out how to do something ends up with Google page after Google page of the same useless stuff.

  • Is it really as bad as these blogs paint it?

    Sometimes I can be, I have seen some bad documentation even on Windows apps.
    It really is the whole programming culture that needs to have a mindset change.
    They need to care about Documentation more so other people can pickup where they left off
    It also saves programmers the time of having to answer needless questions.

    Has it come down to using Google before a man page?

    If you deal with obscure software, yes.
    I know I had to use google quite a bit the first time I was building lapack and cblas.

    • Re: (Score:3, Funny)

      by godrik ( 1287354 )

      It also saves programmers the time of having to answer needless questions.

      Don't worry! I have scripts to answer RTFM to whole forums at once. I do not even have to read the post. Just to be undetected sometimes the scritps replies "Read the source Luke" instead.

  • Well, if you're talking about official documentation that comes with a particular application, or HOWTOs on various subjects, I think there is a lack of good documentation for beginners etc. in quite a few areas. But most distributions have help forums, (some better than others) and that plus a little googling provides lots of very helpful information for the less experienced users. Remember back when any application you bought came with a big fat manual (the paper kind, I mean)? I'm thinking of when I w
  • by mark0 ( 750639 ) on Thursday December 03, 2009 @11:28AM (#30310594)
    I have found the Ubuntu Community Documentation [] to be pretty good for cookbook procedures. Their forums pick up the slack for acute issues.
  • 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)

    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 prob

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

  • The question in the summary shows the extent of the problem. No, a man page is not proper end-user documentation. It's great for a trained IT professional who quickly needs to look up the syntax for a command. But for my mom or my wife's dad, even getting to the man page is a challenge - and to get there, they need to know that man pages exist. Are there even man page viewers for the desktop? Ones that are readily accessible and preinstalled with the default system? But I must come to Linux's defense, too.
    • Ironically, (Score:3, Insightful)

      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:comman

  • Do they mean Linux or the distro? This is an important distinction here. I never looked at Linux' documentation; didn't even know it had one except the comments in the code. But, with the bewildering number of distros, I can see the issue there to any newcomer.
  • 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?
    • Re: (Score:3, Interesting)

      by value_added ( 719364 )

      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 wor

  • I'm sure there's a lack of GUI guides - most advice is to paste some obscure commands on the command line. But my biggest issue has been documentation that's just not relevant anymore. When they refer to switches that don't exist, configuration files that have changed formats, dialogs that aren't where they're supposed to be, or where basically the whole way of doing things have changed. Or it refers to an ancient command line way of doing it because the GUI tool didn't support it, but now it does.


  • by thethibs ( 882667 ) on Thursday December 03, 2009 @11:41AM (#30310774) Homepage

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

  • by aussersterne ( 212916 ) on Thursday December 03, 2009 @11:41AM (#30310776) Homepage

    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

  • 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 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 DarkFencer ( 260473 ) on Thursday December 03, 2009 @11:57AM (#30311040)

    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.

  • 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 jimicus ( 737525 ) on Thursday December 03, 2009 @12:32PM (#30311688)

    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)
    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 /.'s moderation system. In an ideal world Google could pick up on this and show helpful replies above unhelpful ones.

    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.

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

  • 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 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 SleepingWaterBear ( 1152169 ) on Thursday December 03, 2009 @05:27PM (#30316516)

    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.

"Paul Lynde to block..." -- a contestant on "Hollywood Squares"