I saw an article on Slashdot yesterday that asks the question "Is Linux Documentation Lacking?". It's talking about the quality of Linux documentation for the "beginner to apprentice" level users, the many ordinary Joe's and Jane's that give Linux a try only to end up going back to the platform that they started out on because they have the worst time trying to wade through the documentation trying to learn how to do things.
I've had a few go-rounds with Linux myself and I am not a hamster, I have to say that a lot of documentation for Linux software is definitely "Fail". A lot of it is woefully out of date and most of it is written in man page format which in and of itself is ok but let's face it, man pages can be more of a royal pain to read than the most obscure textbooks you'll ever use. You find yourself wading through screen after screen of in-depth details about every option and command for something when basically all you want to know is "how do I do x?"
I think that a lot of Linux software could use some more simply laid out help files that are built from a functional point of view with examples of at least the more common uses for something. I've found that when a help file is written that way it's a lot easier to digest because I think that for most people learning by example is an easier approach. We don't always necessarily need a total rundown of everything something can do.
Oh, the man pages should stay, because there are plenty of times when that level of detail is needed but people writing documentation should try to remember that usually most of the people who use it will not have the level of expertise of the people who created the program or wrote it's documentation.