Slashdot Mirror
Is Linux Documentation Lacking?
eldavojohn writes "A number of blog posts are surfacing that are calling out the helpful open source community on their documentation. No, not the documentation for the highly skilled technical people, but the documentation from beginner to apprentice. A two-part series by Carla Schroeder lists bad documentation as 'Linux Bug #1' and advises users to use Google as the documentation. We've discussed before some of open source's documentation being out of date. Is it really as bad as these blogs paint it? Has it come down to using Google before a man page?"
But on the flipside, I tend to use Google as the documentation for Windows/MacOS and most assorted non-free software that runs on them, too.
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.
Athiesm is a religion like not collecting stamps is a hobby.
first.
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.
As the island of our knowledge grows, so does the shore of our ignorance.
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.
GeneralKael -- Slacker Extraordinaire
The PHP documentation is online, and you can comment on every page. Sometimes it’s really helpful to see what other people have said about a function, how they used it, or problems they had and how they worked around them.
A static documentation doesn’t have any of this. You get what you get, that’s it.
Alexander Peter Kristopeit bought his basement from his mommy for one dollar.
I find man pages to be poorly written, and difficult to understand most of the time. I tend to use google to find people who are discussing it in plain english...
The fact is, Google in most of the times, provide a list of posts in some forum with a working sample code.
Face it, users nowadays weren't looking to understand the process, they just want a quick solution (even if it risk installing a rootkit).
Think Ubuntu Community. sigh~~~
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.
Best Slashdot Co
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.
As a Linux neophyte, google has *always* been my choice. It's been my experience that man pages don't provide the context and examples I need to use tools completely foriegn to me. Of course...I've never relied on MS help files either. Prior to Google searching, my path to success involved knowledgeable folks around me and actual written documentation. I think every OS and application author or publisher should consider reworking contextual help so new users have quality help that's easily found. Like a link to Google in every app.
Huh?
.nosig
do new users even know Man pages exist? also another issue with man pages, I think, is for new users is that they are written for other technical users on the whole and not your aunt vera.
Anon Coward.
I google for man pages.
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 provide examples of usage.
[John]
Shit better not happen!
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.
All documentation sucks now a days. I default to Google for documentation on everything. Microsoft doesn't even really ship docs anymore they just link through to their web documentation. It's just the way of things now. You'll get more and better info from thousands of bloggers and forum posters than you can expect from any doc team.
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 was using WordPerfect 5.1 in DOS. Well, those days are gone, and the "missing manuals" which you can buy are both very expensive and sometimes innacurate. Sure, GNU/Linux and associated applications and DEs could use better official documentation, but there's a lot of good information out there as well.
I have found the Ubuntu Community Documentation to be pretty good for cookbook procedures. Their forums pick up the slack for acute issues.
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.
See my blog http://ilovecookes.blogspot.com/ for light hearted technical information.
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.
Tutorials are a fucking problem. That and pointless screencasts. Nobody can refer to documentation to get the facts needed to solve a problem anymore. They all need the problem *directly solved for them*.
Coupled with people's insistence on using "new media" like videos to "teach" information that should be written clearly as a reference (rather than a "how to do it" guide) and the amount of totally unqualified/unskilled people who insist on *TEACHING* (usually to gain attention, or worse; AdSense revenue) we're creating a generation of terrible IT workers with no problem-solving or research skills whatsoever.
Tutorial-based development is practically the leading paradigm for new graduates doing monkey-level coding work nowadays.
I don't think so.
Come down to? Man pages are a standard from 30-some years ago, intended for expert users (the only kind there were back then).
Of course, if we could all agree on a standard that meets today's needs, that would be another step up. A place with natural tools for a help forum and links to publisher documentation to get user-tagged and wiki-edited into user-friendly, version-referenced documentation over time, and more importantly, one which was the consensus one-stop-shopping place for this kind of stuff. To get the user base, it couldn't be restricted to Linux tools - it would have to be universal.
...pages are impenetrable I find the ubuntu community docs quite helpfull though it is hard to find the right page to your problem innitialy
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.
True, the built-in Linux documentation is often lacking. But in spite of that, it's much, much better than the built-in help files for Windows or Mac.
No matter which OS I use, Google is always my first stop for technical help. The difference between them is that with Linux, I usually find a helpful site almost immediately (usually on the Ubuntu Forums). With Windows, the best help I can find is usually some obscure, confusing entry at the Microsoft Support website. Ick.
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. The documentation on my latest Windows system is not much better, except that a help system is built right into the desktop. It's the availability of third party printed documentation that makes the difference.
# man linux
No manual entry for linux
Yup. It's lacking
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.
That's because its really difficult to determine what's "Linux" when you're talking about Linux. What works on RHEL/CentOS won't necessarily work exactly the same on Fedora, and will probably be way different than on a Debian box.
Contrast this, however, to one of the BSDs, say FreeBSD, which I am the most familiar with. Let us take a look here: http://www.freebsd.org/docs.html. All of these documents ship with the OS, so if you don't have a network connection (for instance, you need the docs to help you set it up), then you have them there as well. The FreeBSD Handbook covers everything from installation to configuring BGP.
There is a separate Developer's Handbook (which even contains a primer on x86 asm), a Porter's Handbook, etc. The docs that ship with the OS include even The Design and Implementation of the 4.4BSD Operating System, which is somewhat dated at this time, but still a great help in theory.
Then, of course, there are the man pages that everyone always mentions, which are awesome, but don't really help make the point I'm putting forward. Of course, the fact that FreeBSD can ship such thorough documentation is because FreeBSD is FreeBSD anywhere, where "Linux" is not. So, perhaps the problem isn't with "Linux," but with certain distributions not taking documentation seriously enough for the various common tasks and interfaces.
What I'm really getting at is, I should not have to Google around for random blogs and wikis to find out how to do a common task that I may be getting to for the first time, hope that I can find an answer, and that the source can be trusted. Any of the distributions which have any sort of commercial or foundation backing at all, really should just bite the bullet and hire on a few technical writers to actually make proper documentation, and then keep it up-to-date. Hell, even Microsoft updates their online help files, and most tasks in Windows are straight forward enough that only 4th grades and 60 year olds need to ask about it.
Relying on GUI config tools, DHCP, and other magic to keep "newbies" from needing to actually learn anything is counter-productive and isn't going to help create new professionals. "RTFM" shouldn't be a put down or a dirty word, but TFM needs to actually contain TFInformation. Is that really so much to provide?
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.
Sometimes, the documentation is the right answer to the wrong question. For example, I've struggled with xorg.conf to make it recgonize all my mouse buttons and eventually it did, but that should have been autodetected (or from a device list) and a user-friendly mapping tool to let me choose what they'll mean. More "just work", less "documentation you must read because things don't work" really.
Another good example is the media players. I've fiddled with tons of switches there when what I'd like to do is double click and have the file play. It's great that they're there, if you need them. But it's not better manpages I want...
Live today, because you never know what tomorrow brings
My experience with OSS docs is that it is often much better than the docs of Propriety products. The rationale that explains this, I think, is that OSS docs/faqs etc if present, is at a level that ensures that the developer does not have to answer too many questions from noobs. With propriety software the focus is often "We need docs to say that we have a complete package that we can sell" That means that the docs are often absolute drivel and takes you no further than what the UI already provided. At the worst it is just a series of screenshots of the menu's stating the obvious, like "File->open: this opens files". Both camps have examples of brilliance and of drivel, but the propriety products surely excel in the drivel department!
!
It's not the volume that's lacking.
There is no shortage of doorstops for GNU/Linux. There is also no shortage of web based documentation.
However, there is a crapload of BAD documentation.
--
BMO
I'm a Linux beginner with Ubuntu installed in VMware and considering buying a laptop to run Linux exclusively. I don't feel like I know enough to jump in all the way just yet. Google is useful if I know what I'm looking for, but at this point I'm not sure what I don't know yet. Once I know it, though, I intend to educate others, like my non-techie fiance and parents. (incidentally, my Mom loves the idea of Linux as a community created OS)
Is there a list of benchmarks for what I should know as a basic user and what I should learn next?
If Google doesn't know, it is un-knowable.
If a software solution is crappy enough, it is impossible to write document for it. If a program has to be *endured* rather than enjoyed, all its documentation can do is either reinforcing the shittiness experience by point out *how* and *why* it already sucks and un-amendable (if the doc is correct), or dumping more crap on top of that (if the doc is incorrect).
I'm looking at you, GNOME. I used to be a GNOME user but I gave up. The docs was barely useful for anything. I wanted to configure GDM and there's no explanation of those arcane XML shit and event hooks. The conf files were scattered here and there, and guess what, the infamous, incomprehensible gconf that actually brags about being modeled after MS registry! I finally got the idea that the devs simply gave up the idea of explaining their un-explainable clusterfuck already. I don't use a DE anymore.
Mod me however you want. I'm not a karma sink and I don't save it for an afterlife.
Colorless green Cthulhu waits dreaming furiously.
Maybe some comparison to windows' help files would apply to these people.
What I see in everyday use of computers is that the end user experience is primarily based on culture rather than some completeness of built-in assistance system.
Googling answers to common issues of the system is a just next step to asking some techie's advise.
The resolution to the documentation problem is simple. I use it on my projects and when I managed programmers, I made them do it. Unfortunately, it needs discipline--the difference between programming and engineering--which is in short supply in the FOSS community.
The resolution is that you write the relevant section of the user manual first, have the client review it for clarity and sanity, and then make the software do exactly what the manual says.
Pause to recover composure
What could I be thinking?!
I'm a Programmer. That's one level above Software Engineer and one level below Engineer.
I've been a Linux user since 1993 and the state of Linux documentation today is worse than ever before if you don't happen to be an actual coder on a specific project reading project documentation for it in order to facilitate your work and contributions.
Back in the day, there were manpages, info pages, comprehensive documentation at /usr/doc or /usr/share doc for specific packages, and documentation files in nearly every source directory that you compiled yourself. You could also pick up just about any book on UNIX (System V Bible for SysV-like distros, or various BSD books) and apply much of what was said to Linux as well.
Everything was well-understood and common to the general state of things in the UNIX world and if you didn't understand something, a quick apropos/man or info or visit to /usr/doc or /usr/share/doc would result in enlightenment.
I'm a Red Hat/Fedora user since Red Hat 4 (Slackware before that) and as a 25-year UNIX veteran, I often feel like I have no idea what's going on in (for example) the init process, X configuration, desktop management, app resources/configuration, etc. Where are the dotfiles located? Where are the /etc components? What are the command-line arguments? Where are the manual pages? What documentation does exist is generally in the awful "Help Tool" format (click Help -> Help Contents in an application window and get a lot of prose for beginners). This documentation typically offers NO INFORMATION beyond the navigation of the user interface for the application. Nothing on system resources, locations of configuration files, dependencies, APIs, command line arguments, or anything that would allow you to either troubleshoot or modularly re-use the software item in question.
The system-level stuff (PackageKit, PolicyKit, SELinux, Udev, HAL, Plymouth etc. etc.) does not offer any clear location for configuration and typing for example "man selinux" brings up a couple of paragraphs with no detail. It refers to a pile of other manual pages, none of them installed by default. There is no overview. And SELinux is probably the most transparent of all of these.
The desktop is completely unmanageable if something breaks; the dotfiles are not in any concise location. gconf-editor is not installed by default and even after you do install it, there's no documentation on the options that it contains. It's not clear how to cause a command to execute on startup. You can go to GNOME startup options in a menu through which you have to use a GUI program to "add" things to the startup process, but the environment that's being configured for the processes spawned this way is not documented and many attempts to execute commands using this method fail.
More and more it seems as though I am constantly using find and grep either in all dotfiles in a directory or as root through the entire /etc, /usr/share, and /usr/lib directories to identify through keywords or binary strings either binaries or text files relevant to tasks I want to accomplish, then paging through them or opening the binaries up in a hex editor to try to grok what I need to change through sheer intuition.
Yes, I suspect there is documentation "out there" somewhere, but spending an hour trying to Google where it is located in each instance is an hour that I already don't have and that now can't go toward actually reading and grokking the documentation in question. But it appears to be just too much to provide easy directions to the technical documentation that exists, if it exists, in each case.
There is a definite ethos of "try to hide the system from the user" that has emerged in Linux and it does not make me happy, as is obvious here. I now spend several days each Fedora upgrade trying to bang my personal system into the shape I want it to be in. It used to be really simple to upgrade, and it was one of the greatest things about Linux. Just tr
STOP . AMERICA . NOW
My biggest gripe is when a complex subsystem (e.g. audio in recent distros) lacks a "10,000ft perspective". Sure, I can read about all the bits and pieces, but there's simply nothing that treats it as a _system_. Fine to handwave about "this maps this to that", but for crying out loud how much effort does it take to draw a )(*^&)^ block diagram showing the sense and direction of said mappings? Another prime example: KDE (and perhaps Gnome) initialization. How about a step-by-step runthrough of how the various blocks are started, what starts them, where they all read configuration data from, etc, etc. If this exists now, my apologies, but I spent a horrendous amount of time working out how a desktop session figures out the paths of its .kde and Desktop directories from square one. It's _almost_ explained properly in several places, but until I wrote a script to dynamically modify ~/.config/user-dirs.dirs at KDE login it insisted on defaulting back to the "well known" directories for the initial phases. Can I really be the only person who needs to keep their KDE desktops disjoint across host machines when using a common home directory?
To answer the question in the summary - You're kidding, right?
Linux docs are pretty much terrible. I didn't RTFAs but I'm pretty sure I can imagine what they say.
The web forums are disorganized. The plethora of "just different enough that this trick won't work on that one" distros dooms to failure even serious attempts to bring order to this world. The traditional man pages don't have useful examples or appear to have been written as condensed cheat notes formatted for scrawling on the palm of your hand before going into an exam. Yes, you go to google first if you want to have a ghost of a chance of figuring out your problems.
Now, don't get me wrong. There are some stunningly nice examples of Linux docs out there. There's just far too few and they're hidden in the giant haystack of crap, stuff that doesn't apply to your distro, and just plain wrong advice apparently written by griefers.
Interesting timing on this story, though. I ran across a good example last week. I'm having trouble with trying to get video to work in Ubuntu Hardy LTS on a machine with a poorly supported ATI integrated video setup. After much reading, I finally find a few pearls that talk about bypassing X and using framebuffer output. Supposedly VLC and mplayer can both do this.
I'll spare you the gory details. But if you want to test this, I challenge anyone to locate online a reasonable set of command-line examples that show how to start those programs in this mode, examples that can be understood by a reasonably competent user who simply hasn't dealt with this stuff before. The couple (and there were *just* a couple) of command-line examples I was able to locate after hours of searching made all sorts of assumptions about the command-line competence of the reader.
Ultimately, the docs just weren't good enough to do the job. That is way, way too common in Linux-land.
How many people actually study the manual that come with any product? I've been using Linux for so long that I'm not certain what would go into a beginner's guide to Linux. Does Windows come with such a document? Do Windows licensees find it useful? Do they even read it?
UNIX/Linux Consulting
The open source community is essentially a huge collaborative composition of people with various skills and interests that drive the results in a direction that is essentially a function of all those participants.
So, if you are some clever blogger who points out that the documentation is lacking for a certain group of people then the reason for it is obvious. None of the active participating components are people who care about the type of documentation.
The fundamental problem with this style of production is that only the manufacturers will be consistently pleased with the results. Today many people are interested in the software but unable or just unwilling to participate in its creation. That includes documentation of course. So until they are able to participate somehow, their interests will rarely, if ever, be represented.
In a way this is where commercial entities could really benefit this system. A commercial entity has interests beyond their own. In fact, in most cases their interests for the production are entirely outside their personal interests. A commercial entity that wants to rely on, say, KMail for their mail client in some one-off OS based on Linux may have a customer-base that is largely non-technical. Perhaps they are selling network kiosks to elderly or something. They will be particularly interested in proper documentation or help systems that appeal to those highly uninitiated.
But what happens with those actual real commercial entities with real needs for these types of missing components? It seems that they have a tendency to branch and the work they do that would benefit the average consumer of this software never ends up back in the main lines. Maybe because the mainline maintainers don't care, don't like it, or maybe because of licensing issues or perhaps... perhaps nobody gave it any thought yet.
At any rate, it still boils down to the same thing. The a classic "OSS" community developed project will generally only have features that are desired by the contributors. If you're lucky you'll have some contributors that seek to look out for others' interests but that seems to be incredibly rare in this subculture.
If maintainers of software cited for lacking this kind of documentation care about this issue, they should be proactive about it. There is an entire class of concerns that will rarely be raised by the sort of person able and willing to contribute to an OSS project. These concerns include aspects of UI design that benefit less technically savvy individuals and, of course, user friendly documentation. If the maintainers want to excel in the production of their software they need to reach out for these types of features. Find people who can provide the materials but don't know or want to know the processes involved in making the contributions themselves. Find commercial entities that have already done the work and try to integrate what they produce, or ask them to do it.
I read the script, and I think it would help my character's motivation if he was on fire. -Bender
I wonder how many millions of man days have been squandered trawling through outdated (and irrelevant) documentation because the author or poster could not be bothered to put a date on the document, or to specify which version of the software it refers to.
And all those all but abandoned websites which claim to list Linux friendly hardware but which list only antiquated items which can't even be bought in the shops any more. You would be doing the world a favour if you deleted the whole site. And don't even bother to explain that someone somewhere might possibly still have a need to configure Ubuntu 1.0 using a piece of junk sold in the nineties.
But maybe the worst type of documentation is that found in forums which ostensibly discuss problems and supply answers. In my experience, one can find hundreds of web forums in which the simple most obvious questions are answered (ones where the person asking the question could have found the answer for themselves in a trice) but the difficult questions are asked over and over again but nobody has the answer. Why doesn't the developer document their own software? Why when i search for documentation for a driver does Google take me to countless forums where the blind are leading the blind? Who links to forums where a hundred people all have their say, but none actually resolves the problem?
Do Microsofties leave all that crud lying around the Internet to sap the will of the unwary Linux newbies?
Date your documents. Make it clear right up front which particular bit of software and which version your documentation refers to. If you know full well that there is a separate rival project, name them and include a link. Don't waste everyone's time trying to pretend that your project is the one and only, while you know full well that there is another project which does a better job.
How many times do I have to read about ndiswrapper before I actually discover the name of the native Linux driver I need?
If you are one of those responsible for this sorry state of play, shame on you. You haven't helped anyone. Your contribution is just the spanner in the works.
JFGI
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.
STOP . AMERICA . NOW
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 openoffice.org 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 OO.org provided more information or catagorized the output along the lines of tutorials/videos, manuals etc rather just whatever google spits out.
And OO.org is one of the better sites.
Yeah, but don't even try to ask for any help, you'll most likely get an RTFM response. XKCD said it best: http://xkcd.com/293/
:)
I think it's safe to say the documentation isn't really lacking, but the support is...
I generally far prefer the linux documentation that I have read over most proprietary documentation, and I would also say that on the occasions when I've needed a technical question answered, the open source community has been faster to respond than most support contracts I've ever used.
Nullius in verba
What do you need documentation for when you've got the source code? Just read *that* if you want to know how the program is supposed to work.
And how many FOSS developers are nodding their heads in agreement right now? Sad, sad, sad!
"My country, right or wrong; if right, to be kept right; and if wrong, to be set right." --Senator Carl Schurz (1872)
Seems to me that this is the biggest avenue of attack that the open source community could make against proprietary software, as improving the docs would most certainly up the number of users. Problem is that the open source developers often have a knee-jerk reflex of candidly dismissing all criticism of new users on their software, especially when it comes to "user-friendly" issues. However, if they would just swallow their pride for a moment and take a lesson or two from the proprietary folks, they could really make a much bigger dent in the computer world.
Nothing is more frustrating than the knowledge that something would be two minutes simple if only you could find documentation on it SOMEWHERE, but you are forced eventually to download an SRPM and grumble through someone's source and launch scripts to locate the one simple argument that you needed, wasting an hour on what should have been a 30-second manpage problem--only the manpage doesn't exist.
STOP . AMERICA . NOW
Assuming a linux distribution consists of 1) the kernel, 2) gnu utilities, 3) secret distro sauce, 4) other stuff, then we have:
1) The kernel has a directory "documentation" with some half-assed READMEs that haven't been updated in ages. If you want help, well, ever tried getting help on lkml? Ok, I wasn't entirely fair. There is tldp and some of the material on it is actually quite good, but it is a website, and not manpages. Ensure it properly formats in plain text and make it easily installable locally and you have improved the situation quite a bit.
2) Most of the gnu utilities come with texinfo documentation, with a captive reader that requires you to love emacs for it to be usable (altough an also-insufficient alternative exists, it does roughly the same stupid things, so it can be ignored for this argument), and that half the time will show a manpage stating that for the REAL documentation you'll need to look at the texinfo documentation, silently insulting you with its captiveness (because it ignored $PAGER even for the manpage and couldn't just bail out because it couldn't do its job, which is showing info pages and not manpages--the existing solution for reading manpages is vastly superior to info) and the implication that you now have to write that documentation yourself. In short, high-proof top-notch GNU workflow fail.
3) Some distributions actually "do" some "documentation", but usually html on some site elsewhere, or html on your hard drive, tops. There is an exception that started a whole project to "create man pages", but most resulting manpages are "tickmark tickers" and as such completely useless. Some are copy-pastes of standards documents, telling you how the system OUGHT TO work, but not how it actually works, or where the latter differs from the former, or how to practically and portably use it, which is what you want to know.
4) For the rest, the best you can expect is shoddy html or a README in an obscure location. You might very well find that the documentation is automatically generated (say, by doxygen) which means you now need five different toolchains to extract the information from the source into all supported formats, only to find that it again is tickmark ticking snippets that aren't actually useful because they are written from the perspective of someone who already knows the source, and who only writes documentation because that's supposedly good karma. If you want to write something against the software, you now have five different formats that tell you the same: Some, but not all, low-level details, and no overview, giving no idea how to use the interface as opposed to this single function. Often the descriptions are mind numbingly dull, like "This function has a parameter. The parameter is named myintparameter and this parameter is ment to convey a value of myintparameter's type." Useful. If you actually want to use the software, you're SOL. Just like that.
So yes, yes indeed. The state of linux documentation is poor to very poor. Now, before anybody exclaims that other (commercial) software does worse, yes, there are others that do worse. But there are others, including free ones, that do better. It is usually the BSD family that comes with very usable manpages and at least FreeBSD has had a documentation project that tries very hard and more often than not succeeds in providing suitable overview material, tutorials, FAQs, and so on and so forth. To meet or exceed that standard would be a worthy goal. Achieving that is also very clearly a long way off.
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.
http://www.beanleafpress.com
All one need to do is compare Microsoft's CMD.exe documentation to Linux Man Pages.
Drop into a command prompt; every single Batch command is fully detailed in both:
1) What flags do
2) Robust examples of usage.
While this may not be Windows-proper if you are going to compare Man pages to Windows documentation, at least compare it to the most similiar instance. CMD.exe help and help on command-line commands (/?) blows man-pages away.
And as other posters have noted there is so much duplication/mirroring of man-pages online that often it is difficult to find anything except that repeated information ad nauseum.
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.
one of the best sources of documentation I've found (for solaris) is sun managers.
It's not a wiki, it's just a mailing list. But there's no back and forth. You post your problem, people reply to it directly to the poster and the poster posts the answer back to the list after having tried it out.
I've not come across anything this brilliant in the linux (or bsd) world and it would bear repeating.
I'm not sure that is documentation in the larger sense, but in the smaller 'solving a particular problem' sense it works fairly well.
Get the howto writers to stop using Vim. Seriously, people who are used to windows are driven away by stuff like that, just tell them to use nano!
I only buy pepper spray that's been tested on anti-vivisectionists.
...for the intermediate user, or weeks-past-beginner user, anyway. Getting the basic commands down wasn't a problem when I first started using Linux, but I stumbled into an enormous gap between the easiest stuff and the more advanced stuff, where it seemed like some key knowledge was presumed but never, ever spoken of. man pages without examples were one regular frustration, and having to search for thirty minutes just to figure out how to track down a simple, crucial piece of information. It was a little like the house in Beetlejuice: sometimes I'd search for help and find a perfect little model village, obviously tended with care, and sometimes I'd open a door onto a vast, yawning desert filled with vicious candy-striped worms.
Article is out of date but there is at least a link to a dead site citing the latest article. (Can't expect them to keep links up-to-date on an article that is static by nature.)
Lack of updated, relevant & accurate documentation is another example of the [potential] benefit of paid-development software vs. free: documentation is one of those software development tasks which really should be done but nobody wants to do it badly enough to do it thoroughly without compensation.
Oh sure there are isolated counterexamples all around. Paid software all too often has lousy documentation; some labor-of-love FOSS projects are marvelously documented. Overall, however, it's money that makes a lot of good things happen that wouldn't otherwise - like making sure all levels of documentation are correct for a given package.
And now I return to reconciling a foot-high pile of printed documentation, motivated only by tomorrow being payday...
Can we get a "-1 Wrong" moderation option?
Somebody modded this insightful? WTF?
Google first, rtfm later. This is what Linux's great popularity and google's great indexing has given us.
Most Linux distributions do indeed have poor or incomplete documentation. The interesting realization I had with respect to this is that it usually doesn't matter - with the massive power of a search engine like google and the large number of users asking questions, you seldom really *need* the docs to figure out how to do something. You can almost invariably ask your question (in English!) to google, and get an answer in seconds that would take you minutes or hours to cobble together from fully reading man pages and online manuals.
I came to this realization when I was recently evaluating FreeBSD as a replacement for Solaris. In truth, both of those systems have excellent documentation, but getting things done with either system can actually take longer because the volume of 'internet wisdom' surrounding them is less due to their smaller user bases. With Linux, almost every question has been asked by some clueless newbie, answered, and indexed. With less prevalent systems, the question may have never even been asked in public. People just read the docs and figure out the answer on their own. And google never indexes this.
Good documentation is good. It's also hard. And in projects run by volunteers, it can easily slip through the cracks. In a lot of cases, though, what people need is not proper documentation, but knowledge of how to do something - and in such cases, documentation may no longer be the easiest way to find out how to do it.
Does the pope shit in his hat?
YES!
right now, "Use the source!" and "Documentation is bad!"
Use the source: "I do not develop this software for income, I do it for free out of the kindness of my heart because I find it interesting. I do not find writing documentation to be interesting, so I won't do it. You are free to read the source and do it. The strength of open source is that you have the source. Therefore, if you want documentation, the source is where to start, because I'm certainly not going to write any." >> This is a fair point, but these projects, totally lacking in documentation, should not then be included by distributors in base installations or as critical system components. It is simply bad to incorporate documentation-free components into the core system. If nothing else, distro maintainers ought to find someone to write docs before including these components.
Documentation is bad: "Users do not want to read documentation, and therefore won't. Since we can assume that they won't, the system should 'Just Work[TM]' for you without it. If it fails to do this, the system is at fault and you should file a bug report and/or contribute if you're able, but the need for documentation is evidence of bad software design." >> This attitude, increasingly all-too prevalent, is the one that I really can't stand. Really. The essential argument here is that software should never be flexible because users are all identical. That, to my eye, is a losing proposition long-term and I'll never think it's a useful perspective.
STOP . AMERICA . NOW
For most of the desktop apps I use, the MAN pages and Web documentation offered to users by the apps' developers seem to lag a couple of versions behind the code.
However, using Google brings its own problems: as other posters here have commented, you tend to find more people asking the same question than you find answers.
Even on forums that do have the answers, they're often buried on the tenth page of "me too" comments responding to the question.
Those forums would be a lot more helpful if, from time to time, someone went through and deleted the cruft, or edited every posting of a question to include a link to the answer, so that the useful information would get a better pagerank.
Better yet would be if someone were to paste the useful answers into a Wiki page, editing them to include some context, and make clear which versions of the app and which distros the answer applies to.
But who would that someone be? Where would we keep the Wiki page? And how would we credit the poster of the original helpful information, and the owner or operator of the forum where they posted it? (If you don't think that's important, then you haven't understood the psychology of a lot of these forums and their users....)
If you follow the links to http://www.kde.org/documentation/ and read the "Application documentation" paragraph, a lot of those links are extremely old:
http://docs.kde.org/development/en/kdebase-runtime/userguide/ last revision date 2004-06-16
http://docs.kde.org/development/en/kdebase-runtime/faq/ last revision date 2005--01-19
http://www.kde.org/info/ no date, but aRts? No Plasma?
It's inexcusably irresponsible, especially since they've completely re-written KDE. Doing certain things can be a big hassle. Configuring workspaces properly is rather complex. KDE users shouldn't have to scour the Web for documentation, and no one should have to remind them to update it. Isn't part of software development maintaning accurate, timely documentation?
Yes, there's http://userbase.kde.org/Plasma/FAQ/HowTo, but where's the link from the main documentation page?
Safe BrowsingDiagnostic page for fatamorgana.com
What is the current listing status for fatamorgana.com?
What happened when Google visited this site?
Has this site acted as an intermediary resulting in further distribution of malware?
Has this site hosted malware?
How did this happen?
I allways thought the linux documentation was Google.
I don't look in man pages, I google the name of the command and the action that I want to do. Google will point me to a web-accesible man page if it has those words on it, or to a blog or forum post otherwise.
Let's improve google, and the linux doc will improve, too.
Yes.
The obvious next question: Will it ever get better?
And the Magic 8-Ball says:
"Very Doubtful"
I am not making this up. The Magic 8-Ball has spoken.
deleting the extra space after periods so i can stay relevant, yeah.
Yes.
May I ask how would you find out about that task on a Windows machine?
Weaselmancer
rediculous.
Does the pope shit in his hat?
No, no no, it's:
"Do bears shit in the woods?" and "is the Pope a Nazi?"
Straight, user-directed thinking. Amazing. Ya don't see much of that nowadays.
http://xkcd.com/627/
I have worked with programs created by commercial vendors, closed source, and the documentation is horrifying. Not worth the paper it is printed on. All for the purpose of selling support.
I find Linux documentation to be far better than many commercial products.
Of course I think Google is the best source of documentation for most programs.
Let's be honest: Documentation of open source programs is generally TERRIBLE. Anything unusual you want to do usually requires a week of experimentation.
If computers were for smart people only, the Mac would never have been invented. Documentation... Documentation... We don't need no stinking documentation. Man pages are great if you need to do something at that level but emailers and surfers don't require man pages most people don't even know they exist. Non technical people have some difficulty with man pages because they "look to technical". I have to admit that I use google for looking up almost everything I use Windows/Mac/Linux/UNIX systems on a regular basis. Having a single point (browser) to search for stuff reduces the time switching between systems to find something.
I'm a sysadmin, and have been for about 6 years. I manage a mix of Linux, Windows, and Mac machines, with few DOS boxes and a couple running some version of Solaris on them. In general, there's no good documentation included for the problems we have with any OS.
Since this thread is supposed to be about linux, I'll mostly stick with that. I go straight to google for almost everything, at least the first time. Why? Because the man pages are mostly illegible. There's actually too much information to be useful when I'm trying to figure out how something works. If it's one of the few that has meaningful examples with explanations, fine. Otherwise, I'll go back to explanations written in english. And if I don't even know what command I need, forget it -- there's no way man pages are going to help. And lets not even get started with man pages that tell me to refer to the info page...
So when are man pages useful, in my opinion? When I already know the command, and just need to be reminded which flag to use. Basically that's the only time I use them... the rest of the time, it's easier (and frequently quicker) to look it up using google.
Now... I also do some programming, though I'm not very good at it. I document everything. The last thing I wrote came out to about 500 lines of code, and about 50 pages of documentation, including design decisions, details on the database backend I used, SQL layouts, installation and setup, lists of things that still needed fixing (which have been updated as I fixed things), and a beginners guide. I also built argument listings into the script, so using a -h flag would tell you what you needed. Once we started using it, everyone just came to me and asked questions, and I think I'm still the only one who ever read the documentation. So I can sympathize with not wanting to bother -- if no one is going to read it, what's the point? Still, I'd like to see more.
Linux documentation is coming quite close to Google first. As a matter of fact uShares documentation sucks so bad that I had to resort to Google > IRC to fix my problem. Even then IRC didn't fix it and my own will to 'explore' fixed it. But then there is no place for me to document my fix so well I guess people are just going to have to deal without.
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 (http://tldp.org/) 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.
Gentoo? I've found it to be rather good.
Maybe you're not a ricer though and want to use something mainstream like redhat/centos?
Have any of these people actually RTFM that they are saying is inadequate or lacking? What is the author's definition of "good" documentation? The docs I've found for linux have generally been superior to ones I've come across from Oracle, Novell, or Microsoft.
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!
What is the benefit of open source if the openness doesn't actually pragmatically exist? Openness implies access, understanding, knowledge, transparency. Without documentation, none of these exist. Yes, you can get ahold of the source package shipped by your distro, extract it into files, and study the source code as documentation.
You can also run all of Windows 7 through a disassembler and you can make changes to your own system with a hex editor editing DLL libraries by hand. That's nearly the same kind of "documentation" and "openness" as far as most users are concerned, yet nobody would seriously make the argument that this brings any kind of "openness" to Windows 7.
STOP . AMERICA . NOW
Same applies to documentation: if something can change, and lots of code does, I do not want to have to change both code and documentation in the same, dependent, way. There are two ways out: 1) automatically generated documentation, which admittedly is pretty ugly and schematic; and 2) archived searchable forums and discussions.
Coming at this from the perspective of a professional Linux sysadmin with quite a few years experience, I find a lot of forums downright painful.
Not because they're difficult to use or search - Google does a perfectly good job of indexing them - but because they are frequently a case of the blind leading the blind. I really have lost count of the number of times I've looked on Google to solve a problem, found a few forums and discovered two things:
1. I'm at a much more advanced point in the process than the OP. (Not really a problem, more an annoyance) /.'s moderation system. In an ideal world Google could pick up on this and show helpful replies above unhelpful ones.
2. The answers given are downright wrong, and demonstrate clearly that the person writing the answers has no understanding of what it is they're talking about. Which I wouldn't know were it not for (1), above. The forum software itself needs some way to mark replies as "helpful" or "unhelpful", much like
Mailing lists for the specific thing you're having trouble with tend to be better - largely because the barrier to entry for posting on a mailing list is rather higher.
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.
STOP . AMERICA . NOW
The man pages had (and still have) the same problem that a dictionary does: you have to know the command with which you need help before you can look up how to use it. Example from a month or so ago: I was having an issue with a binary telling me "no such file or directory" when I tried to run it. It wasn't the binary itself that was the problem (obviously, IT existed!) but rather it turned out to be a missing dynamically linked library. I didn't know that the "ldd" command even existed until google told me; man pages are sort of useless in a situation like that.
It keeps out the riff-raff.
Subject line says it all
How about a Linux version of Clippy? Instead of a paper-clip, a penguin with an AK 47. The bullet holes guide you to mouse stroke movements. It'll be a hit (no pun intended) with the younger gen.
Table-ized A.I.
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.
http://www.maxineudall.com/2010/02/should-economists-be-sued-for-malpractice.html
"Has it come down to using Google before a man page?"
Yes because more people know how to click on a web browser and look up something on their search engine of choice then go to a command prompt and type man <program>. Also not all programs have man pages so the web search has more information. Also my last experience with man pages showed references but I couldn't really click on those references to see other information like a web page lets you do.
Good documentation including screen shots of various steps to show people what they should experience can make a world of difference then some basic text on a screen in a command prompt window for new users. Going the extra mile to highlight various screen shots for each step in the process of performing tasks with your program can really be helpful when married with clear meaningful text.
~~ Behold the flying cow with a rail gun! ~~
Documentation for ALL software, hardware, regardless of vendor, has gone down the drain. man pages are not as useful as they used to be. Windows Help has gone down the drain. Commercial software, private software, doesn't make any difference. Why pay someone to write a good manual when you can sell a consultant instead.
This is my sig.
I suggest more real world examples in the man pages. I frequently find myself trying do tasks that I think would be relatively simple and common, only to to find the examples lacking and having to wade through and decipher dozens of obscure and poorly explained switches.
Man pages are more, IMO, for refreshing than learning. If you know what you want to do and want to learn how to do it, man pages aren't a great tool, because they are organized in a way which is useful for people who already know the command to use to acheive their goal, not for beginners.
I'm OK with computers in general and Windows in particular. I'd deeply like to be able to competently install and run Linux, and recommend to friends & family, but so far I'm running into several issues:
1- Much documentation is required. Setup is less straightforward than Windows. Both because I know less, and because there are quite a few weird issues: VLC working badly until you configure video driver such and such, Wifi card support a bit iffy, some packages installing badly and screwing the whole system...
2- Documentation is hard to locate. Sometimes it's an official HOW-TO on Ubuntu's website, sometimes it's on the developper's site, sometimes it's a post in either forum, sometimes somechere else...
3- Documentation is not very up-to-date. Ubuntu releases every 6 months. Forum posts are usually not updated, Ubuntu, Dev's docs, and how-tos seem mostly 2 years old. You HAVE to do a Google search for docs since no single site is enough, and then there's much clicking and weeding out to do before finding, maybe, an answer for your question for your Linux version. Or you can try some older solution, which usually won't work, but might.
4- There's precious little documentation for the Linux newb. Or rather, there is for the absolute newb, but not for the Windows wiseman switching over to Linux. I'd like to quickly do in Linux what I'm doing in Windows, even though I barely understand Linux. Most somewhat-advanced packages' docs (the Remote Desktop Protocol thingy, rsync NTFS to ext3...) assume a good level of Linux knowledge. There's no "here's how you do that in linux" for the 10 most common tasks an advanced Windows user does (remote control, backups, moving data directories, setup mobile apps on usb dongles...).
5- The forums are not that great. I got a useful answer 50% of the time. Sometimes I got flamed because the question had already been answered (which I mostly missed because of not using the right search terms), or the post was "old" and I wasn't sure it still applied, or I didn't understand / couldn't implement the answer... In the end, I got ashamed and discouraged, and no longer dared ask my stupid questions.
In the end, it took me about an afternoon to get VLC working. I never managed to get the RDP server working, nor the rsynch backup from my main PC. My 'experimental' Ubuntu PC is right now booting mainly in Windows, and I'm not calling the experiment a success. Although it did install faultlessly, in the end I'm not confident enough to make it my main machine, nor to recommend it to friends and family knowing I'll end up having to do support for them. And it's mostly a Documentation problem, I'm sure Linux I could do everything I want.
The Cloud - because you don't care if your apps and data are up in the air.
Every developer knows that documentation is important. You know what else is important? Core functionality. Protecting against buffer overflows. Preventing seg faults. It's a bit of a catch-37 (which is not quite as ironic as a catch-22): without proper functionality, the system is useless; without documentation the functionality is inaccessible and the system is therefore useless. So do you spend your time implementing or documenting?
Stale and missing documentation is a legitimate criticism of Linux, just as it is a legitimate criticism of Windows and the majority of both open source and proprietary software you're liable to encounter. The main difference is, you're not paying for anything with (most) Linux. Plus, open source developers are frequently accessible on mailing lists and IRC channels, so if you have a question, you can ask the horse himself, instead of his outsourced stable boy. Last but certainly not least, it's open source, so crack open the code and start figuring it out yourself. Or if you can't, you can always go back to those mailing lists and IRC channels and find someone who can (or more likely, already did).
Slashdot is not a game, Slashdot is not a game. Crap, I just lost points.
Of course its terrible! I have been using Linux for years but I still use Google over many man pages. Take something simple for example like the "find" command. This is an essential and powerful tool, also easy to use. But I challenge you to find a new user who could figure out how to type in the command in its entirety and correctly perform a search using just the man pages. Its nearly impossible for them without any examples, and man pages almost NEVER have any examples to help with syntax.
Man pages are fast a quick to search, what we need are some examples in man pages as well. Also better online documentation would help. Like a Linux How To Wiki. This would be helpful because looking up several pages/forums online can be very time consuming and frustrating for new users (causing them to give up and quit using the OS).
Online Help: I know that when I need info on a topic, I now search wikipedia often by just going to Google and typing in "subject-to-search wiki". The top hit is always the Wikipedia page for my topic. I wish we has something like this for Linux, I would definitely use it, and add to it! While I know there are a lot of Linux Wiki's there I don't know of any that provide an all encompassing support of all linux functions. Also I don't know of an easy way to search for them from Google like I can Wikipedea.
the terms surrounding this software in a way that belies many of the benefits routinely claimed by open source advocates.
Of what do "access to," "freedom to," and "re-use" consist? Does not the "millions of eyes" trope imply an actual base of users and developers that are conversant with the code? Does it not require information? Do you honestly mean to argue that the "millions of eyes" in question are beginning with "Line 1" of the Linux kernel and reading through it line-by-line, then proceeding to glibc, then to Xorg, before installing, so that they are prepared to participate?
I can tell you as a developer AND technical writer that when I make a bug report, I have rarely read the code for the project in question... and the extent to which I provide details in the bug report is directly proportional to the amount of documentation available to me to help me to determine the basic architectural layout of the project. More documentation about how it works and how it is supposed to work = more detail (and usefulness) in the bug report. Less documentation and it can just come down to "It crashed. Fedora 12, RPM version X."
Openness does not exist in a vacuum; its benefits do not proceed from the legal construct in question. The benefits of openness proceed precisely in the end from the social availability to users of knowledge about the software they are using. This is the starting point for patches, supporting or following projects, bug reports, and all of the other things in the open source "economy."
It absolutely does not begin with every would-be open source community participant reading all of the source in question, from square one, without any idea of how the larger architecture of the system fits together, which body of source to read first, how the system is meant to work (big picture), and so on. It's simply disingenuous to argue this.
STOP . AMERICA . NOW
... nerd rage at it's finest! 4tehw1n!!!111!!!1!111!one
I'm not sure I follow, can you rephrase in the form of a car analogy?
the preceding comment is my own and in no way reflects the opinion of the Joint Chiefs of Staff
Absolutely it is.
I can offer a bit of a case study FWIW. I'm a technical person (programmer) and along time Windows user. I recently installed Ubuntu on my laptop to dual boot alongside Windows. I had a few bumps in the road during this process. I'm now trying to configure it and get some software equivalents to the Windows only apps I had been using. I can't even count the number of times my quest for answers landed me on an article or forum post that begins with 'open a command prompt'.
I know I can open a command prompt, but I don't want to. There's a psychological thing that makes you feel like you could mess things up easier at the command prompt. I can't imagine the frustration of non-technical people trying to do this. And this is talking about Ubuntu which as gone to great strides to make it more newbie friendly. There is still a way to go. The good news, is that it's very, very close.
For example, there are two ways to add programs - the Add /Remove programs option and the Synaptic package manager. Why two? And having to add more repositories to get access to other packages is strange to me. How would a user know to do this? Why is it necessary? I get it, but a novice might not. Etc.
There are two things, in my experience, that are holding Linux - and indeed, the majority of open-source projects - back. Firstly (in no particular order) is that documentation is generally nonexistent, inadequate, outdated, or even actively misleading. When this isn't the case, it's too frequently written from the viewpoint of someone who already knows exactly what they want to do, they have just forgotten where the button is. I've been using computers for thirty years (running just about every common OS there's been over that time period), and programming for most of that - and I still come across too many cases where they're using a different term than I would have used, and thus it ends up being a steeplechase to try to figure out how to do what I'm after. I also am frustrated at how often I need to try going to the documentation in the first place - if it's a simple, frequently-performed task, it should be fairly intuitive, which would indicate that after as long as I've been using computers, I should be able to figure it out! The other downfall I've come across is a "complexity gap" - Linux is, in my experience, fine for a beginning user, and okay for a gearhead... but the people in between are kind of screwed. The basic stuff "just works", and if you are willing to hack scripts or compile code, you can do just about anything - but all too often, if you need to do something even just a little past the basic stuff, you *have* to start hacking scripts.
Sig broken, watch for
The biggest problem with Linux documentation is the use of Info files instead of man pages. Yes, OK, it was cool that they were working on an early hypertext... but they did such a horrible job of it that flat files in /usr/share/man are more useful.
linux got in my opinion really great docs. there are hundreds of really carefully written howto's, man pages for nearly every program, fora and google. i mean, really! and the best thing when you search for something linux, is that you don't get bothered with ads and shit all the time and nobody tries to SELL you something. also they set standards in layout and data formats. of course there are man pages rigid and abstract as fuck which can drive you crazy when you really need something fast, but that doesn't mean they are bad or lack proper info - mostly people are just to stupid or lazy to suck them in anyways (have you ever visited a package's readme file under /usr/share or downloaded source code figure something out? just asking...). however, with documentation it's the same like it's with code: linux is ours, so if you need something nobody has implemented before, you'd better stop complaining and fire up your favorite editor...it is a community project in flux which relies on participation, or do you think the people writing all the howto's got paid? that's the prize of our freedom. if you don't like it you'd be better off accepting microshit's "authority" or at least admit that you are kinda lazy bastards used to pay for readily made "products". what do you like more, mcdonalds or a good homecooked meal? got to get cooking if you like to eat a REAL meal. cooking has quite a steep learning curve. you mess up meals from time to time - and learn from it. man, when i first installed linux on my box i thought i got a trojan because of the strange symlinks under /lib/i686. i cleaned them recursively with cleanlinks, the system never booted again. i didn't even know how to add an user and shit. today i administer a nice home lan with dozens of servers and cool stuff (hey, i got the tlg-e in my lan and a hurd image runnung under kvm!:-), compile my own kernels and automate everything i do more than once a day with bash and cron, laughing about my first steps within unix. it's like driving huge trucks (in europe of course, with all the narrow places in italy and england). it needs one or two years until you can shove a hangler back into a loading bay without even thinking about it. but in the end it's way more fun, secure and usefule than driving a car...if you don't like trucks, just don't drive them.
Facts:
- Yes, documentation sucks. This is because there are very few people who are both knowledgeable about what "the code" (meaning currently packaged distributions; bleeding edge stuff is a different kettle of monkeys) does and also like writing documentation. (Put aside being good at tech writing for the time being.)
- Things constantly change. As an example, Ubuntu's 6 month window leaves non-techy people breathless at the rapid rate of change, but at least it sets expectations. The tech publishing industry simply isn't capable, right now, of releasing books that fast, even if you assume the can opener of someone competent, willing, and able to write a book targeting the next release. I'm as quick to joke about M$ or Apple's release schedule, but the Missing Manual types at least have a target to hang a book release cycle on.
- Googlicous search is hit or miss, and humans have a cognitive bias emphasizing miss. The seven times you find exactly what you need to know (score!) are mentally outweighed by the one time you couldn't get your new video card to work.
Which all leads me to: the best way to run Linux is to be involved in the community. Folks in the know are much more willing to help you on a message board, IRC or whatever than to spend a week or six writing documentation. The payoff is much greater: someone happy at your interactive investment of two hours of partial attention. Contrast with the investment of a couple of weeks writing docs to see email from someone with weird hardware and poor attention to detail flaming you for "causing" them to lose their term paper.
Not everyone who wishes to run Linux wants to engage geeks on IRC. There is a mismatch there. But I don't see that changing.
There may well be an opportunity emerging for knowledgeable communicators - a $10 service targeted at narrow niches for people like my grandmother's new boyfriend - a non-geek who runs Ubuntu and manages his own website, but is generally clueless about what to do in the face of a problem. The niche is narrow; it has to target the impedance between wanting a fix now and waiting for me to be able to provide family tech support, and it has to actually work for his particular problem. And I think it looks more like tech support than publishing. Anyone who's read Rainbow's End by Vernor Vinge might see the model of 411 service here.
I forget what 8 was for.
In OSS there is a tendency to code first (and if you are good - design first) and a year later someone else will try to retrofit user documentation. This will never work right. And this is why:
In order to have a possibly reasonable documentation, the design and code must be easy to explain. There should be relatively little user-visible corner case, feature X should behave similarly to feature Y even when they are designed/coded by different people at different times.
In OSS what usually happens is that developer X has an itch and implements his stuff without thinking about developer Y doing a seemingly different feature (proprietary S/W is no better). They end up with a documentation that has to cover 2 different features with subtly different ideas. Very confusing.
It is quite possible that feature X and Y are technologically independent, but that is not something the user should be aware of (most of the time). This means that it requires more work to make them look similarly from the outside, so that it is easier to document.
Consider for example the concept of a "file system". Most of the time the user does not have to know if this is XFS, NTFS or EXT4. The documentation is relatively simple and covers 99% of cases. However, if every file-system had different system calls, documenting it would be hell.
If every application has a different UI short-cuts and concepts, it is much harder to document. Why can't it resemble other applications? Because the coder did not consider the cost of explaining and documenting the thing, only of technology (certainly), functionality (probably) and ease of use (hopefully). But documentation was written only after the fact. At that point many concepts and ideas are set in stone, changing them to ease the use and documentation ranges between difficult to impossible
I have gone from the wrong direction and then seen the pain of the users too many times. I hope I learned my lesson. It is simply impossible to document the beast in a reasonable way down the road.
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!
Having both linux and windows boxes in my house over the past 10 years, I'd end up on google for both. One thing I noticed on the linux side, I'd end up at the gentoo wiki more than anywhere else. The wiki was generally well written, with updates and notes along the way. It'd offer multiple options, and was easy to follow.
Aside from proprietary needs, I'm not sure this is really an issue. (It pains me to admit this, and trust me, I'm not a fanboi) Ubuntu handles all of this seemingly well, as does most of the major distros. Personally, I believe that most people are going to hit google regardless, because it's just habit. From my windows days, google was the place I went by default. If people will be adding something, popping in a new piece of hardware, etc, they're already in the mindset that they can hit google if they're questioning anything.
Yes, compared to the *BSDs for instance Linux documentation is definitely lacking. I am a BSD user now but I used to use Linux too before I wisened up.
For example, show me the documentation for an experienced sysadmin who's never dealt with LDAP before, to configure and fire up openLDAP. The middle of '06, I spent nearly a month googling, asking on mailing lists, and fighting with it. The "documentation" was garbage, and appeared to assume that I had the time to read the code and understand the zillions of lines of it.
If I had, I would have rewritten their tools so that a) they gave correct error messages, and b) they didn't require deeply obscure sets of switches just to do normal things like searches.
mark, author, Egoless Documentation, SysAdmin, June '06
...Because it never comes to their mind to type "man page" at the command line!!!
(seriously now: what the heck is with you Unix guys? typing "manual" was too long for you? or using "help"?)
just put some real-world examples at the beginning of the manpage and you're good...
The MAFIAA is a bunch of mindless jerks who will be the first up against the wall when the revolution comes
All but the first line of the grandparent comment was generated by the Firefox plugin WOT, Web of Trust. I just copied and pasted from "View Web Source".
The grandparent comment demonstrates an example of the poor quality of open source documentation. That site not only has poor documentation, but it also tries to exploit vulnerabilities in your browser.
A month or two ago, I was trying to find a place that would have current man pages for everything. I tried http://www.linux.org/docs , clicked the "Linux Man Pages" link, and..... file does not exist. I checked again today and it still doesn't open.
In my experience, bugs are a bigger problem than documentation. All the computers in my household (mine, wife's, two young kids') run Linux. I'm the only one who's a Linux power user. My wife has only started using Linux this year. My kids have basically had no big problems with lack of documentation. E.g., my older daughter, who is really into art, was highly motivated to learn gimp. I handed her a book on gimp, but she never opened it. She just preferred to google for tutorials.
I'm not saying the documentation situation is heavenly, but the bigger problem is bugs. For instance, my wife is not able to get the Line In sound input to work with Audacity so that she can digitize her old Who and Dylan LPs. It's not a documentation problem. It used to work, but it just seems to be broken on the current version of Ubuntu. On my own linux box, the sound output level always goes to zero every time I log in. I raise it, and then 15 minutes later it lowers itself again. Yes, I've reported the bug. When I hit a web page with a java applet, firefox crashes. Again, it's a bug, not a documentation issue. All of my family's current usability problems have to do with bugs, not lack of documentation.
Find free books.
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.
Don't thank God, thank a doctor!
Complete documentation of code (including manuals) is probably the single greatest service that can be provided for an existing project because (a) it makes it much easier for new developers to step right up and help; (b) helps narrow the breach between users and developers; and (c) helps users use the project.
The difficulty is engaging with a developer who has already thought everything out and persuading that developer to critically go over all that work all over again. If you can do that, you can collaborate to write awesome documentation, but it's really hard work.
Developers should try to engage documentation writers from the beginning of that project. Although it will be a pain to have to explain your work and insight to somebody else, the rewards would be awesome.
...but a bad analogy.
You can also run all of Windows 7 through a disassembler and you can make changes to your own system with a hex editor editing DLL libraries by hand. That's nearly the same kind of "documentation" and "openness" as far as most users are concerned...
Well, most users won't be able to do either, it's true. But if they actually wanted to make an effort, the learning curve for editing source code is far less.
It's also worth mentioning that the open-ness does, in fact, have visible results. One example is an open bug tracker, which you won't often find on a closed source project -- you can actually submit a bug and watch developers handle it (or ignore it). Another example is the ability to fork a project and add features -- the fact that individual users can't do it doesn't mean they can't reap the rewards when other developers do. A good example here might be Iron, a fork of the Google Chrome browser.
Documentation absolutely is important, and there are large gaps. We do have some of the important bits -- man pages, plenty of stuff on Google, and the README and HACKING documents provided with source code, for those who actually want to make changes.
But then, plenty of people do find sufficient documentation to develop an understanding. You say "none of these exist", but the sheer number of contributors to the Linux kernel should be evidence that they do, to some extent.
Don't thank God, thank a doctor!
...resulted in the author saying that it's quite disparate and unwieldy. The report was titled "Where Linux Kernel Documentation Hides" and was written by Rob Landley. So things aren't much better for kernel programmers either...
No manual entry for userfriendlylinuxdocs
The Kai's Semi-Updated Website Thingy
I believe that the FreeBSD handbook is the gold standard for FOSS documentation outside of man pages. Oh, and info(1) can suck it.
Thanks,
AC
Rare is the Linux software that even supplies a man page any more. And when they do there, typically, is no "examples" section as one finds in most of the commercial UNIX OSes you encounter.
I especially love the packages that do supply a man page that consists of one line that informs you that the real documentation is found via "info". Then there are the info pages that seems to be nothing but the old man page. This doesn't need to turn into a Gnome Vs. KDE war but I can't think of anyone who'd argue that we can't freakin' pick a single documentation model. I'd, humbly, suggest the old man page style. It's fairly portable so anyone writing software that can be run on UNIX or Linux can write the documentation once and be done with it. (Jeez, is nroff markup really harder than creating an info page or setting up a wiki. And let's not get started on how you even read the support wiki when you're working on a system that doesn't have the network up and running.) And please add an "EXAMPLES" section if some of the command options are arcane enough that a simple memory jog isn't enough to let one know why you'd want to use the "-xyz" switch.
Apart from the man/info page vs. Google problem is the problem of really crappy installation instructions. I've run into too many that leave out significant steps. I'm sure they were obvious to the developers but, since Linux software developers often change the way they develop their code and the installation options often change at the same time, it's really important to make sure the lowly INSTALL file actually contains all of the steps needed to install the package. (Hey, not everything comes in a handy RPM or whatever your package manager of choice uses.) And you developers that write fancy web-based installers that ask all sort sorts of detailed questions: Make sure you are actually using that information. For example, if you ask for the database administration password, your installer has the means of checking for and, if necessary, creating the database, users, etc. your software uses. If you ask that sort of question of the user, s/he's far more often than not going to assume that you needed that information in order to do a bunch of tasks as that administrator. Asking for that information and then leaving it up to the user to perform all those tasks and then not even mentioning that in the INSTALL file is one reason why Open Source software has a bad reputation. (I won't give commercial software a pass on this either. I know of one package that made a big deal about their software running on a particular flavor of UNIX. Technically that was true but not until you editted a half dozen scripts and configuration files to correct the errors that prevented Java from running. While their support critters were insisting that it ran "out of the box", I had already started modifying the company's SOP for installing that package to include the list of files that had to be fixed before turning the system over to end users.)
BTW, Carla's blog entries on this were spot on in several areas. Suggested reading if one hasn't done it yet.
CUR ALLOC 20195.....5804M
The current state of the documentation for most typical Linux packages are:
Man pages: Out of date, and refer yout to the info pages for more recent information. /usr/share/doc: Copyright information. Exact same information for every package, but exists seperately for all of them.
Info pages: Starts with copyright, then covers everything you don't need to know.Doesn't cover anything beyond the man pages, even though you were refered here. Usually just an exact copy of the man pages, spread over several pages.
Tex pages: The same as the info pages, just paged differently.
HTML info: Either copies of man pages or info pages.
Who would win this election: Andrew Weiner vs Andrew Weiner's weiner.
Nothing like documenting every command-line option but giving NO EXAMPLES. So then I'm left having to read what -a, -b, -c, -d, -e, ..., -z do, and having to check EVERY letter to make sure I'm not missing something. 2 or 3 examples added to every man page would have saved me 20 hours out of my life. Consequently, I rarely use man pages anymore. But hey, I'm just a windows user who runs cygwin and uses unix command-line utilities to make life easier. If I had to run my entire operating system with man page documentation, I'd give up. (Because I have. Really. I have better things to do than spend time dealing with makefiles and compiling, when I can just download a pre-compiled binary under windows.)
-Clio
Karma: Bad (mostly from not giving a fuck)
Blog: http://clintjcl.wordpress.com
Good excuse for an impromptu vacation, eh? "Uh yeah, the man pages strongly suggested that I should go to Massachusetts"
I listen to both RIAA and non-RIAA stuff if I like the music, tangential business/politics nonwithstanding.
Are you serious? We (as in, humanity) neither need nor want Linux to be well documented for the neophyte. It'd be a counter-productive move, resulting in a lot of dissatisfied users.
You've got three, maybe 4, basic kinds of users, in my mind. Yes, stereotyped a bit, but I'm trying to make a point.
1) The technically inept who know it, and "just" use their computer within the limits of their intuition. They don't read much of anything.
2) The technically inept who doesn't know it, trying to change things, getting themselves in trouble. They read documentation, and try to make ends with it.
3) Technically inclined people who don't like to read documentation, but can figure things out with a point/click interface well enough (see: the bulk of Windows administrator types).
4) Technically inclined people who read documentation, and don't need "Windows" style useless documentation which can be inferred easily enough by looking at the menus/etc.
There isn't any room for "beginner" documentation there. A graphical UI is supposed to be self-documenting (which is, I believe, one of the earlier GUI selling points), and if that isn't enough, then you've either got to use something else to get the job done, or there is a fundamental design flaw in the UI which should be rectified.
The one form of beginner/newbie documentation I could recommend being more 'forefront' would be a guide to how the system works (Xorg/kernel/multiuser interaction, etc.), which resources to use to find more info (man, info, apropos, etc.) and so on. It wouldn't have to be long - just a page or so, printed. But it'd certainly push category 4 in teh right direction, as well as provide category 3 with enough information to get what they need, when they have to.
~/ssh slashdot.org ssh: connect to host slashdot.org port 22: too many beers
It's not lacking... Every time I use man on Linux I get a friendly page saying "SEE ALSO info *"
Right, just like Ubuntu, or any of the other "mainstream" linux distributions... unless it gave you the infamous blue screen of death because of some hardware problem, misconfiguration, or malware. Windows is not magic, it can and does malfunction just like every other OS.
And at that point, if Windows did not pop your box, your OS documentation will help you.. how? That's the question this /. topic is addressing - how does the OS help the clueless noob in trouble?
I submit to you that both linux and MS-Windows suck in this regard. Speaking from experience here! Every single damn time I have had an MS-windows problem I have chased down a total blind alley in the help system (which only really works if you have functioning Internet, and then it usually says "See your system administrator" - very helpful!). I have less trouble with linux, but that's only because I have an understanding of how computers work and can read source code.
In theory, linux docs for n00bs in trouble should be much better than windows. The bazaar should easily trump the cathedral in this instance. However, in reality, both of them suck.
And it's because we're all posting to slashdot instead of writing new doco...
man tcp/ip repair "Just Google it!"
What if the thing you need help with is installing drivers for your NIC? You can't access Google 'cause you don't got no internet!
I ran into this long ago when I tried installing Linux on my laptop. I was dual-booted and it was my only PC, so I had to reboot to windows, search the webs, reboot to Linux, try something, reboot to Windows, etc. A real pain in the arse.
Of course that was a long time ago and in think default drivers have gotten a lot better since then, but man those were tough times!
Saying Linux has bad documentation is like saying Windows can be unstable or unsecure at times. In both cases it is the nature of the beast. I've played with both OS's for quite a while now (Windows since 1992, Linux since 1998) and they both seemed to be stuck to be what they are.
I've always felt there was too much documentation. Information overload is very easy with linux.
I thought it was up to each Distro to maintain the relevant docs for their stuff? I've been using Gentoo for a long time now and they have great documentation. Here's the ATI howto/FAQ, for example: http://www.gentoo.org/doc/en/ati-faq.xml That wasn't cherry picked, look at the rest here: http://www.gentoo.org/doc/en/
If i can't find the info i need i check the software's homepage (probably from sourceforge) or search the forums. Lastly i search the web *shudders* but that is where info-overload comes from.. so much there from present day to decades old.
PS: i'm at work and IE is previewing this post as a super tall box only one word wide.. hope it doesn't post like that : /
http://soylentnews.org/~tibman
No it's not. It saves newbies from crashing their system and wondering "What did I do wrong?" It also saves us from having more blackhat hackers.
As someone who has repeatedly tried to set up a small music computer lab to work of Linux and open software, I can testify that the documentation for setting up ALSA and the Linux Audio subsystem in general is the worst documented in all Linux distros we've tried. Developers either seem to hope that audio cards will respond to default configurations, or expect the person installing to be able/familiar with the intricacies of ALSA (which, BTW, not only is easily the worst online documentation I've come through, but once set up, even with "compatible" cards, breaks really easily). Some of the problem, of course, has to do with manufacturers not releasing specs, etc., a situation which is even worse with professional audio cards than with top of the line video cards. And I don't mean to pan the work of people who get ALSA and OSS and the audio parts of kernel working. Yet it must be said: it's precisely this situation and the lack of real documentation for troubleshooting, that has prevented us from switching to Linux. It's hard enough trying to wean our students from Windows when even we teachers can't get our systems working.
I looked but could not see any reference to FLOSS Manuals in the replies to this post. It's early days but they have an interesting approach to the problems mentioned in the post. http://en.flossmanuals.net/
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.
This assumes that you know everything you need and want - and everything you will ever need or want - before you commit to a particular distribution.
If nothing else, distro maintainers ought to find someone to write docs before including these components.
In a lot of man page you can read : This manual page was written by XXX for the Debian project (but may be used by others)
look at the poor documentation of the security model of MYSQL
I always thought the worst aspect of the manpage system was that the examples for usage were at the bottom in most. How many times have you pulled up a command for a quick refresher only to scroll through 20 screens of details to get what you wanted?
Man pages are not tutorials. They are not help pages. They are reference material, designed to quickly and briefly inform the experienced user about the usage of a command and any related files.
Info pages are the next step up. They are often more detailed (witness the Emacs pages) but they are generally written for a technical audience and quite frankly, the average user isn't going to find them anyway or be able to do anything with them if they can find them,
Man pages and Info pages will, if you are very very lucky, be written by the authors of the software who speak the same language you do and are used to writing technical information. They stand some chance of being updated as the software is updated.
Next up on the list of information resources is wikis, hosted at the site where the development is done. These will generally provide more accessible information for new users, will be community driven and hopefully will reflect the state of the code in the last two years. Keeping wikis up to date is a huge task for large projects.
Beyond that, proper documentation requires constant community involvement. Most projects don't have someone looking after the docs - the software is the focus. Even teams like GNOME and KDE struggle to keep their docs even vaguely up to date - witness the dearth of information on the latest release of gdm (2.28.1) for example. And these teams do have volunteers who are trying to keep up with the changes.
Forums actually give the best location for problem solving because they quickly acquire a list of problem reports that are the things that 90% of people hit. These show up clearly in google and will, hopefully, get solutions posted or FAQs written.
Until the non-technical users of Free software step up to volunteer to write and maintain documentation for software projects, there will always be a lack of current, complete and easily accessible documentation. However, good documentation is hard to write and I often find that commercial software projects are distinctly lacking when it comes to good writing, so I don't think this is an issue which is restricted to open source software.
Cheers,
Toby Haynes
Anything I post is strictly my own thoughts and doesn't necessarily have anything to do with the opinions of IBM.
Good design with a GUI means documentation is not needed IMHO.
Back in the day, two decades ago when I was first starting out with comptuers and learning dos/unix, you really had to look up the documentation and study how things worked, because the interface was a epic discoverablity and learning curve failure.
Then came the GUI revolution, everything changed. Since then, I can't think how many times I've downloaded a application and just started using it, figuring it out on the fly and slowly moving up to more advanced usage. It is what I expect from applications.
Good design means documentation is seldom needed, and for basic applications never needed at all. A GUI gives you a lot of room and many methods to present contextual information to a user. At worst they can click on a link to take them to further detail. Having meaningful and plain english descriptions and other information right in the interface mean studying the documentation is utterly not necessary.
But we've had another paradigm shift since then, away from the GUI desktop app the next generation of application, a web app. These needs no documentation, because the format of a web page *is* a document itself, at least has evolved from that, and is a format that fundamentally begs to be descriptive and visual.
Going back to linux reccently and having to use a man pages it suddenly occured to me how primitive and out-of-date linux documenation is. Basicly, man pages predate the era of the hyperlink. It ironic that Google is a superior help tool to much of what comes with applications.
The solution for linux then is a wave of right-brain web-savvy thinking. Developers are never going to spend time writing comprehensive technical documentation for all levels of use, and having done such technical writing myself I would not wish it on my enemies. The solution is in the web paradigm, link relevant helpful information in context, embed the help right in there, rather than send users off to Google.
You know what.. Google *is* a command line interface, and a good one, how ironic.
After logging in slashdot still does not take you back to the page you were on. It's been that way for 20 years.
and find a book called Ubuntu Linux for Dummies
Their they're doing there hair.
Jealous? ;)
Every time I start to have faith in humanity, I ruin it by driving to work between 7 and 8 am.
The problem is that any documentation that does get written gets outdated very quickly. This compounds the problem since people will be using older versions of software and only find recent documentation or people will be using new software and only finding old documentation. This leaves the user the necessity of picking which parts are relevant from sources based on knowledge that there is no easy way to gain without experience. For instance, installing Oracle 11g on a Xen hosted VM. As long as you pick a distro with a PV kernel in the installer you're pretty good to go, otherwise you've got a lot of work ahead of ya! Should have seen how long it took me to get Ubuntu running in a VM. Ended up having to steal a Debian kernel since Ubuntu stopped supporting Xen for a while. I hear it will be back soon though when they catch up to the latest kernel that Ubuntu is running.
I have been using Linux for years, mostly because of working on a Unix box for years also. It taught me a lot. I have been through most of the distros but landed squarley on Arch Linux. Why you ask? Becuase of it's powerful wiki with it's power to answer almost any question you have, it makes it the best Linux distro I have used yet...http://wiki.archlinux.org/index.php/Main_Page
Learning to use the "man" command is important, ...
But only SOME of it is in "man". (And "man/apropos" is polluted by the enormous number of X subroutines documented there for people writing X clients.)
Some is in html hypertext that can be reached by various "help" keys scattered around menus and applications.
Some is in "info" - a legacy text-based hypertext browser from the GNU project. (You have to navigate it with emacs-style keystrokes, rather than using a browser (though I've seen browser-based access to it in a redhat distribution).) When an "info" documented application has a man page at all it typically is very sketchy and says it may be out of date and non-canonical, with the real document in info. (I'm a vi-thian rather than an emax-ian so info's navigation system bugs me considerably.)
IMHO "info" documents should have been ported to html by now and a single, perhaps browser-like, interface to ALL the documentation (not just parts of it) with decent navigation, indexing/indices, and find features, should be available in any given linux distribution (preferably all of them) and MADE OBVIOUS to newbies.
= = = =
When trying to learn the system itself, a bigger problem even than the flaky and scattered documentation is the lack of "breadcrumbs" in the graphic interfaces to the various configuration tools, which give you no idea what configuration files they manipulate and what they do to them. This interface-candy acts as a barrier to learning the guts. Linux (and its collection of system daemons and their related file arrangements) was historically administered by direct configuration file editing. But linux configuration file arrangement and daemon compliment is enough different from the other unixes that internals lore learned on the latter doesn't always transfer well.
Bantam Dominique roosters crow a four-note song. Once you've heard it as "Happy BIRTHday" you can't NOT hear it that way
One problem I hit with a lot of online Linux documentation is the pages don't list the date they were last updates, or don't list the version of the software they apply to.
It's very annoying to find what seems to be just what you are looking for, and then an hour into crafting a solution based on that, you find that it depends on a particular feature of some program, and that feature was substantially changed two years ago.
No. There are many things that you might want a system to do without a GUI. There are many instances (embedded development, or quasi-embedded systems/headless role-oriented systems) where you don't want to even install the GUI, much less a web browser.
This is the Linux development that troubles me... the perception that the important thing for Linux to do is become a great browsing and multimedia platform, and the right way to do this is throw everything that's not directly supportive of this singular form of use away--simply discard it. In the midst of all of that, the incredible flexibility of the UNIX paradigm for a variety of computing and data processing tasks is being lost.
STOP . AMERICA . NOW
". . .not the documentation for the highly skilled technical people. . ."
Is this because you're assuming that type of documentation is good? Well it's not, it's terrible. I love the linux, but the documentation is poor on a technical level for many things.
Working with solaris for example can be very annoying, but sh*t is actually well documented. Even their beta stuff has reasonably good documentation for gory technical details.
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.
As does Arch Linux and FreeBSD. In fact, I think the FreeBSD handbook should be held up as a model for effective documentation of an entire operating system. It's generally well written, extensive, and covers instructions from basic day-to-day system use and set-up to complex networking and system administration tasks that can be solved with solutions provided by the base operating system and associated ports. Arch Linux's wiki is also quite good, though it has its flaws. One major problem in searching for linux documentation is that much of it is distribution specific. A lot of newbs go out, get themselves a random linux distribution, then in looking for answers are redirected to a different distribution's way of doing things that inevitably doesn't work on their system. This is one reason I funnel a lot of first time *nix users who want to get into it, and are generally technically proficient, towards FreeBSD. The documentation is there for them to self-teach. They've reported decent success with it, as well.
The appalling state of Linux documentation is what got me involved as a writer in the first place, leading me to co-author RedHat/Fedora Unleashed for a while and edit English-language docs for Mandriva.
I ran into two kinds of editors: those who knew nothing about Linux and those who knew "lots". The latter group is what frustrated me the most and are probably very much like the software authors themselves: pedantic and arrogant when it comes to documentation. Poor documentation and "making you work for it" is part of the right of passage for the Linux elite.
You can see this in ESR's characterization of people who ask questions as "idiots" in his 'How To Ask Questions The Smart Way'. Not to pick on ESR, but that shitty attitude about those that feel the need to ask questions permeates the GNU/Linux/FOSS culture. 'Knowing' is what separates "us" from "them".
And that's why Linux documentation is so bad: because it's meant to be, you idiot.
"I believe in Karma. That means I can do bad things to people all day long and I assume they deserve it." : Dogbert
By the numbers, and largely ignoring the fact that Linux is an OS while Photoshop is a design app...
1.) Photoshop simply has a much higher installed user base. Admittedly I've only got anecdotal evidence, but my Linux class in college had about 23 students in it, and there were only two of them. There were a dozen Photoshop classes, all with 30 students or more. Odds are that you're within two degrees of separation from several people who know photoshop. Similarly, every library I've ever been in has at least one book on how to use Photoshop, and even if it's a version or two outdated, much of it is still relevant, which segues me to...
2.) Photoshop is largely consistent. Yes, there are several versions of Photoshop currently in production use, but the core commands that most people are going to use have remained largely consistent, and there's nowhere NEAR as many variables between the different Photoshop iterations and Linux. Gnome or KDE? What Distro? Which repositories are in Synaptic? Are you even USING Synaptic, or are you using Yum? Does your distro use RPMs, DEBs, or simply tarballs? All of those are going to come into play just to INSTALL an application, and will directly affect the steps required. Adding a Gaussian Blur in Photoshop has required the exact same steps since at least 7.0, likely earlier.
3.) There is never, ever, a command line to deal with in Photoshop. I'll completely admit that most recent distros make the command line as optional as it is in Windows, but there isn't even a possibility that anyone will ever need to do anything in a command line in Photoshop.
4.) The average new Photoshop user is more likely to have *some* rudimentary form of graphic design experience than a new Linux user will have in UNIX. I'm sure that virtually everyone who starts using Photoshop has done at least SOMETHING in Paint, Publisher, or hand-drawn something. Others had formal training in manually doing tasks with ink, paper, and film, that Photoshop has replaced. Regardless, there is some prior knowledge that makes Photoshop more familiar to a new user than Linux. Admittedly though, there is enough similarity between GNOME/KDE and Windows to make getting to Firefox simple enough, but even things like the folder structure to some people takes time (explaining that "Home" is "My Documents" is easy, but explaining that "/dev/hda1" is the same as "C:" is a little less intuitive).
5.) Similarly, Photoshop's output is a whole lot easier to determine whether what you had in your head ended up coming to fruition, while Linux isn't necessarily as obvious. Yes, starting a program or closing a window will be obvious, but what about manually configuring an IP address, or figuring out whether you have the proper driver installed? these problems are a bit more difficult for the average end-user to see, depending on their circumstance (i.e. bad video driver is easy, while a multifunction driver might print fine, but not scan, or might print fine locally, but not over a network).
6.) Photoshop's internal documentation *is* much better than many Linux apps I've used. My copy of the Adobe CS3 suite came in a box with about 18 pounds of printed manuals, one for each app. The one for After Effects is an inch-and-a-half thick, and it lists EVERY command you can use for expressions (about as close to a command line as you're gonna get from the Adobe suite), along with the best contexts to use it in, and the syntax of the arguments. The help file mirrors this as well, and covers all of the basics and lots of the intermediate stuff. Additionally, it's not at all hard to find largely simplified tutorials to get specific looks out of Photoshop (stuff like "make a new document...press F7...use these exact parameters...make a new layer...add this filter using these parameters..."). some of this is mirrored in Linux (I was able to find one such tutorial for installing Torrentflux that was written in a similar stepwise manner), but i'd dare say the majority of it isn't.
7.) To build on #6, and ad
THIS NEEDS TO BE SAID:
Good software does not require documentation.
I attended a number of conferences with Bob (Robert) Wallace, the author of PC-Write, Andrew Fluegelman, the author of PC-Talk, and Jim Button (Knopf), the author of PC-File.
These are largely acknowledged as the first successful shareware programs, and all the authors had basically the same philosophy, but I wlil give you the nutshell version given to me by Bob Wallace:
"I don't sell software; software isn't real; it's all up here", at which point he waved his hands on both sides of his head, and then continued, "I sell manuals".
This paradigm, where the revenue is tied to the documentation, which would be relatively expensive to reproduce, whereas software was relatively easy to copy, is what drove shareware sales for Buttonware, Quicksoft, and others, who depended on their software being copied, and then people coming to them for documentation when the software was hard to use, due to it being intentionally non-intuitive.
As software designers, we've never gotten out of this rut (for the most part), and it's seen as useful to have online help and other extensive documentation for something that should be actually simple, as well as conceptually simple. Ironically, we've even gone to online documentation, either supplied on the distribution media, or on the Internet, or some combination of both (like Microsoft does), in an attempt to reduce publication costs without having to change our design paradigm.
I even have a friend who is actively *proud* of this; he says things like "If it was hard to write, it should be hard to use", and similar gems (he's my friend, but that doesn't stop him from being an idiot).
For tools intended for use by programmers, yes, there should be documentation; there's only so much complexity you can abstract there. But for finished products, if you can't start them up and just start using them for their intended purpose, then there's something wrong with the design.
-- Terry
Man pages are only semi-useful if you ALREADY KNOW WHAT COMMAND YOU NEED.
Try man -k
I think what they are looking for is
man -m real_documentation 8)
man -k cd is not useful.
But man -k dvd yields
brasero (1) - Simple and easy to use CD/DVD burning application for the Gnome Desktop
dvdauthor (1) - assembles multiple mpeg program streams into a suitable DVD filesystem
dvddirdel (1) - Deletes a previously authored DVD directory structure in DIR
dvdauthor (1) - assembles multiple mpeg program streams into a suitable DVD filesystem
dvddirdel (1) - Deletes a previously authored DVD directory structure in DIR
dvdunauthor (1) - Removes DVD-Video file structure
growisofs (1) - combined mkisofs frontend/DVD recording program
so man -k or apropos is useful if you can ty enough different words.
"I believe in Karma. That means I can do bad things to people all day long and I assume they deserve it." : Dogbert
Yes, official Linux documentation is lacking. I've always held that the success of any software relies heavily on its documentation. Look at Delphi. When the now-defunct Borland released Delphi 7, it came with a pretty decent set of content-sensitive, F1-accessible help and examples. Nowadays I'm using Delphi 2010 from CodeGear, and yet I find myself firing up Delphi 7 and looking up what I need in that version's help because the D2010 help sucks so bad.
I'm in no way suggesting that Linux is not successful, but it would be a lot easier to use if it came with beginner documentation. It's safe to say that it's no longer just a hobby OS, and we're far beyond the point when Linux, the various flavors of GUI desktop, and all the applications moved beyond "man".
*** *** You're just jealous 'cause the voices talk to me... ***
Caroline Rose edited Apple's Inside Macintosh, a set of books that let me support my family for several years. Other than that, I can't recall seeing any documentation that wasn't a simple port of GUI menu structure into linear text. The dearth of answers to the questions "why?" and "wherefore?" is stunning in its Bauhaus minimalisticalisation.
On the other hand, having written code nobody fresh out of college could understand (the guys, i.e., who write versions greater than 2...), I can understand the desperate need to ship before documenting before plunging into the next vat of we-need-it-yesterday.
You'd think, with all the time in the world, and no pressures but the self-imposed, Linux documentation could exceed the need to spew surface and delve never.
On the OTHER other hand, why does a manual have to exist between the pages of a book? Why can't it be Google? It frequently is already. But I would second the motion made elsewhere, to at least append dates and version numbers to your how-tos. Knowledge has a half-life of less than 50 million seconds these days.
``Tension, apprehension & dissension have begun!'' - Duffy Wyg&, in Alfred Bester's _The Demolished Man_
I just have to say after recently setting up DHCPD, it's .conf man page needs serious work. Maybe they should break down the classes & subclasses a bit more & provide some more examples that MOST PEOPLE WILL USE IT FOR e.g enforcing MAC restrictions.
I spent 30 minutes trying to setup a simple MAC whitelist because the manpage didn't provide proper examples of class & subclass syntax. Eventually I worked it out...
After Googling, it seems most people give up, & resort to adding host entries with hardware addresses.
Fantastic...
I naturally get apps from the repository once a page tells me what app I need.
My experience differs from yours. A more typical scenario for me is 1. find an app, 2. search in Synaptic and fail to find it in Ubuntu main or universe, 3. install it from source, and 4. write up a needs-packaging request in Launchpad.
"man man" and learn how to use man first.
Or if you're using KDE, click that big [K] and type "CD" in the text box.
Hey look, "CD & DVD Burning: K3B"
I have never heard of Windows/MacOS before... Is it some kind of hybrid OS that looks like Apple but lives in DLL Hell?
start writing new documentation! Start on the stuff you do know about and see if anyone on the forums is interested in writing docs on their areas of expertise. That's how things get done in Linux.
K I skimmed this whole thread, the core problem & solution are elusive. Part of it is a decline in the 'harmony' of Linux app/desktop design integration, part is the information 'rot' of obsolete threads found on Google. The Gentoo wikis are pretty much the only bright spot here, no one can even cite a good GUI linux app documentation.
I'm not a Linux expert but I spend a lot of time dealing with Drupal which is also GPLed and regarded as a tough learning curve. They have dedicated a ton of effort into not just the documentation and forums but also U of M usability research. I met Dries at the U of M before they went in and looked at how peoples eyeballs scattered in panic because a RED ALERT BOX was worried their user creation password was not secure enough. They got a draft usability plan out of the research:
http://groups.drupal.org/node/9252 - and even video of eyes mapped around the screen.
In this case the information, inline documentation really, came in perceived as too hot by being RED so they changed it in Drupal 7 to light orange bkgnd. You structure the information to direct attention appropriately and then deliver snippets when the environment changes.
Think about it: we have totally divorced 'documentation' from even considering how important little snippets of text are, delivered correctly *with the correct level of detail* AND *the ability to seek up down and laterally in the conceptual environment*, instead thinking of man vs info vs annoying old threads. Probably the most important documentation, definitely for non-GUI Linux, are the small, less-than-ten-line, instructions and advisories that come before prompts. And usually these have HTTP links included for big deals. If everyone tripled their effort here it would work a lot better than just cleaning up the disastrously wrong (or certainly obsolete) design of man and info pages. Could familiar man pages spit out more examples and not exhaustive list of flags? (well it has to if you believe man must only be one page of stuff with all the programmer hooks, signals &etc. Where's the non-programmer material to be found then?)
Good wiki pages for software documentation usually break text into similar less-than-ten line sections, and do so in an up-down-lateral hierarchy of headers. Fortunately this can get exported and stashed into the app. If you had wiki paragraphs XML tagged to land in certain dialog boxes and other points, you could pipe wikified micro-documentation into the apps, even desktop apps. Hell if you just put a "WIKI??" button right there in the modal dialog box or prompt at least half the users would get it immediately. If a clever crew was handling this 'help string wiki' it would work out fine probably.But you'd have to control yr wiki or yr enemies would put in bad Windows YES/NO dialog boxes' help ("Do you want to print or save? YES/NO") just to mess w you.
Anything you present an end user should be structured in the newspaper article style - a pyramid structure leading with 'what does this do? how can i do the 3-5 basic things? why does this matter? what is this related to?' Beyond that you should be able to reach an overview of that part of the system architecture. Like apache2ctl would get you to rc and rc.conf and note what the runlevel is and why / which daemons are at runlevels.
There should be a clear ontology between nodes and levels of information. There is usually no explicit way to back out from a command to where the command fits in the system, or something you can run to lookup what a weird file does. maybe also the Apple 'receipt' type file that is a breadcrumb for packages could be used as a way to pull out documentation from different versions, another big gripe/snag here. There is not a lot of unity between Linux packaging systems and documentation and window managers. Obviously packaging info is already quite helpful but once things are installed it doesn't 'appear' anywhere useful, to other apps (imagine special warnings fo
--hongpong.com
If there is ONE thing that linux is by far the best at, it is making your LAN card work.
Even the proprietary WLAN chipsets from Broadcom?
The problem with all of the above is you are talking about a PS user that has had 'training' via classes, etc. I was under the impression we were talking about a user that had never seen either Linux (or PS for the sake of this discussion) and had to accomplish a task and they were going to use installed documentation. That was the gist of this thread, or so I perceived, apologies if my perception is misguided. Given that scenario and your discussion of Photoshop's manual and notwithstanding the enormous changes in the application since say PS 7 to todays CS versions (which you seem to discount above) the situation is the same. The manual for PS assumes some knowledge of the app based on terminology, etc. Yes, there is a glossary but Linux man pages also point to 'See Also' man pages. Not all that different of a scenario.
If you are in unfamiliar territory and need to know how to do something specific, the PS manual is just as lacking as the Linux man pages and rightfully so, no author can account for all the scenarios a user might run into and some basic needs MIGHT be adressed, I have found the same to be true of many (not all) man pages as well.
What does burn mean? What is the purpose of the Clone tool? How do I use the magic wand or masking or layers? If you think the PS manual is going to help the green user with the above without them having to google a bit I would say you are projecting your own knowledge of the app to a user that knows nothing.
How is this article even possible? Ofcourse you use google instead of man pages.
Lets say I install a new distro, I want to set up a firewall, routing/nat/forwarding (or whatever you kids call it these days), install my specific hardware and get a weird graphic card working properly in X.
What man page do I read? The manpage for "firewall", "internet connection sharing", "xconfigurator"? Nope. I google.
Seriously, man-pages are all good and perky for the nittygritty, but finding a complete solution for the most common tasks are NOT a option. And besides, how do I "man iptables" if the package isnt even installed.
Any new user to Linux would be completely and utterly stunned by the information contained with the iptables package. I cant even make any sense out of it except for the most basic commands after 10 years (not working as a administrator, praise the lord, though).
Comment removed based on user account deletion
I have used Linux for almost 4 years now - and the lack of adequate user documentation finally hit an end! I created a site to help people with Linux, http://www.pkill-9.com/ and I am active on the #ubuntu channel on freenode. The best example I can think of is: k9copy -- No documentation, not intuitive so hey, I run the windows dvd shrink under wine! (works for me!) Wayno
Perhaps those lusers just need to learn how to properly as a question. Here is an example:
Abbott calling Costello
Costello calls Abbott with some questions about UNIX.
Costello: What is the command that will tell me the revision code of a program?
Abbott: Yes, that's correct.
Costello: No, what is it?
Abbott: Yes.
Costello: So, which is the one?
Abbott: No. 'which' is used to find the program.
Costello: Stop this. Who are you?
Abbott: Use 'who am i' not 'who r yoo'. You can also 'finger yoo' to get information about 'yoo'.
Costello: All I want to know is what finds the revision code?
Abbott: Use 'what'.
Costello: That's what I am trying to find out. Isn't that true?
Abbott: No. 'true' gives you 0.
Costello: Which one?
Abbott: 'true' gives you 0. 'which programname'
Costello: Let's get back to my problem. What program? How do I find it?
Abbott: Type 'find / -name it -print' to find 'it'. Type 'what program' to get the revision code.
Costello: I want to find the revision code.
Abbott: You can't 'find revisioncode', you must use 'what program'.
Costello: Which command will do what I need?
Abbott: No. 'which command' will find 'command'.
Costello: I think I understand. Let me write that.
Abbott: You can 'write that' only if 'that' is a user on your system.
Costello: Write what?
Abbott: No. 'write that'. 'what program'.
Costello: Cut that out!
Abbott: Yes. those are valid files for 'cut'. Don't forget the options.
Costello: Do you always do this?
Abbott: 'du' will give you disk usage.
Costello: HELP!
Abbott: 'help' is only used for Source Code Control System (SCCS).
Costello: You make me angry.
Abbott: No, I don't 'make me' angry but I did 'make programname' when I was upset once.
Costello: I don't want to make trouble, so no more.
Abbott: No 'more'? 'which' will help you find 'more'. Every system has 'more'.
Costello: Nice help! I'm confused more now!
Abbott: Understand that since 'help' is such a small program, it is better not to 'nice help'. and 'more now' is not allowed but 'at now' is. Unless of course 'now' is a file name.
Costello: This is almost as confusing as my PC.
Abbott: I didn't know you needed help with 'pc'. Let me get you to the Pascal compiler team.
. . . would you like me to guide you?
Ask Clippy!
I can't say anything about the (sucky) state of Linux documentation that hasn't already been said.
I think the Linux community makes it worse than it has to be with their attitudes.
There are a lot of helpful and knowledgeable people.
There are also a lot of knowledgeable people who are also cranky who RTFM people. There are also people who don't know that much, but who are looking to RTFM people anyway.
It goes without saying that both groups of people don't help the retention of converts and they aren't getting the most joy out of their time that they could be. Watch a fun movie, go on a date or slam some helpless geek.....hmmm what is more fun?
Interestingly, I've noticed that in the Mac and FreeBSD communities that if people don't know the answer to a question or don't want to answer it for whatever reason ( the person didn't provide good info with their question, read the docs, etc ) they will simply not respond.
Imagine that.
Both platforms have better documentation too.
My most comprehensive article on the issues is:
http://praxagora.com/andyo/professional/community_author_collaboration.html
Much more for the curious at:
http://www.praxagora.com/community_documentation/
At FLOSS Manuals (http://flossmanuals.net/), where I volunteer, we're filling the gap with well-organized writing projects combining peer review from the public with experts from various free software packages. There's a very active mailing list and a lot of highly praised output on the web site.
(I may go back to one of the articles cited in the posting and add this comment to it.)
there is heaps of excellent free docs around. for example, have you looked at FLOSS Manuals?
We have been going now for about 2 years and we have many many excellent docs about free software mostly in English (http://en.flossmanuals.net) but also we have an Finnish community (http://fi.flossmanuals.net) and a Farsi community (http://fa.flossmanuals.net) and also many manuals being translated into various languages (see http://translate.flossmanuals.net/write).
for the linux community there is much of interest, but probably most interesting is the excellent introduction to the command line manual which we produced in collaboration with the FSF:
http://en.flossmanuals.net/gnulinux
You can get it here also:
http://shop.fsf.org/
We produce community authored content and we often do this in 2-5 days. For example the following were produced in 5 days :
http://en.flossmanuals.net/civicrm
http://en.flossmanuals.net/CircumventionTools
http://en.flossmanuals.net/Inkscape
http://en.flossmanuals.net/opentranslationtools
http://en.flossmanuals.net/ardour/
http://en.flossmanuals.net/theoracookbook
http://en.flossmanuals.net/sugar
and the following were written in 2 days:
http://en.flossmanuals.net/gnulinux
http://en.flossmanuals.net/GSoCMentoringGuide
http://en.flossmanuals.net/firefox
We also produce books. All of the above are available in printed form (see bookstore on the right of the front page).
We also have produced books in other languages including the recent 'How to Bypass Internet Censorship' book ( http://objavi.flossmanuals.net/books/CircumventionToolsar-translate-2009.12.01-12.02.55.pdf ) which was printed in Arabic for the recent Arabic Bloggers conference (http://advocacy.globalvoicesonline.org/2009/12/05/2nd-arab-bloggers-meeting/) held in Beirut.
all content is free as in libre and gratis
adam
Natuarlly nobody is reading these comments any more.. but for the hell of it. Doc's Suck. Man pages are the worst. Would it kill you to put a simple example in there? I know it makes you look like your an idiot for having people use your code who are not bright (because I must be an idiot for not figuring out WTF your syntax with all options possible could be!). Right now I try to install Thunderbird 3. Downloaded from the 'getthunderbird' site. Uncompressed the folder. Now what? There's a readme file that says if I need help to see the 'getthunderbird' page. Good, this makes sense. I'm on the page - where is the motherf@@king help? Walkthrought? It's not there. I tried running what look like the files that should go...but NOTHING happens when I try any of them. Double click this file...wait...wait..wait... nothing. Now I feel like an idiot because someone else was lazy, short sighted, not that interested in a successful product. Why bother, soon you'll be able to apt-get or yum it so why should you bother. FAIL. So what should I do. I guess I'm just not smart enough for this crap. Noooles - A+, Network+, MCP & Stupid noob who deserves to be a microsurf...I guess.