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 for diff versions INSIDE of a gui of something else) or the user. Package hierarchies are also useful and should appear inline somehow - help clarify the awesome world of Linux DVD writing ;-).
Another side of it is the kitchen sink app design, GIMP the leading example. Since a hierarchical executive isn't dictating design, usually the complex apps lack an overarching 'vision' or metaphor. (You don't need executives but they end up making the usability decisions traditionally) No one it seems has read 'The Design of Everyday Things' which describes the importance of letting users build a mental model of the object's function, which in turn provides them the cues for interacting with the object. The user doesn't need to know how it's wired but they need to perceive that lowering microwave power lowers its heat.
The problem is that Linux of course crams in as many functions as possible to each command, so the average user can never 'perceive' tar command at all. And GOD FORBID (because UNIX tradition tells us so) that the tar man page start off by telling you how to make a .tar.gz file of a directory... because it would be noncanonical to use tar the way 90% of the time you use it AND it would be non canonical to start with a working EXAMPLE of the most common 3-5 use cases. And the man pages are apparently purposed as tjwhaynes depressingly put it "not help pages". Why?! It's a manual to pipes, flags and hooks that can lead you to no other pages in an easy way.
Who decided this and how can it get changed? The fact that no 'front desk' of the OSS community could ever actually get the entire format of man pages straightened out. This is a structural problem of the open source world.
So I decree from the mighty /. thread: Man pages should include the leading 3-5 use case examples. The programmers and doc people have to actually determine these use cases because usability is central. The examples should be at the beginning. And this should somehow magically become 'canonical' in the OSS world. :)
Obviously it would be best over the long run for all packages to expose blocks of help for searching so that you can have an OSX or Google-like exposed help search. It could include all config file names, all flags and commands. The hierarchy to organize this would be similar to the form that the Gentoo wikis take, installation, networking, signals, hardware interfaces and cards, particular apps, etc.
You need to think about points of access to the help system. Where would you come into it? You should be able to drop error numbers and other obvious phrases into a searchytastic box.
I haven't been that deep with Linux lately, let alone touching desktop Linux. But this kind of usability problem plagues everyone - focus on inline documentation and usability, provide examples and let people move around with up-to-date and package/version tailored info. Every OSS project should have 'use cases' and 'skill level' practically as separate extra fields, next to 'license' and 'language'. And you could make a wiki-style participatory user interface dev app (lets wiki up these checkboxes). which would also be a good way to get people to develop add-ons/plugins.