Man Pages in Linux: Your Experience?

The "Why Linux over Windows?" thread has been discussing the quality of Linux documentation.

SlowCoder states:

There definitely is a balance between software and the documentation that supports it. [snip] Linux is an excellent operating system, with excellent packages, but it takes darn near forever to learn its nuances unless you go to a 3rd party like LQ and ask questions.

To read more of SlowCoder's comments, please view his post here.

That being said...
Please share your experiences in using Linux documentation. e.g. Do you tend to search the forums or head to the help files first? When you were new to Linux, which did you find more helpful? Which is most helpful to you now?

Has anyone ever written any documentation? What is that experience like?

Please, no "us" v. "them" posts. This is not that type of thread. Thanks.

used to be searching from books + help files(locally) first ... and they always work in the ends ...

but nowadays ... seems to me i need to search forums and the like first by the way of googling ... and they dont always work in the end ...


.

i think people expect too much from man pages. they are there to tell you 'how' not 'why'.

I follow a set routine when I run across a Linux problem whose solution I can't figure out.

1) read the man pages - you can learn alot just in this step alone...
2) read the Distro/Project documentation
3) Google for the error message/problem
4) Search the LQ forums for previous posts dealing with the problem
5) Post on LQ.org if I get here with no solution

Out of 7-8 years of using Linux, I've had probably 90% of my problems answered in step 1, 98% answered in step 2, and all but ONE problem answered by the time I hit step 3. The one that sank through I ended up posting at LQ in the security section (RSBAC/PAX Gentoo kernel issue), and unSpawn assisted me in figuring out what was wrong.

Because of my success rate with man pages, I voted "help files".

You forgot online tutorials

I think they all have a very important role and they depend on the nature of the problem and on the previous knowledge of the user.

There are quite a few cases:

1. You have heard that a command might do what you are trying to do, and therefore you look in the man pages for the exact structure. Reading a whole book for just one command is useless, and asking on a forum or googleing takes much more time.

2. You want to do something more complex, such as run a http server. Then, it is recommended to read a book, to understand every detail. A man page doesn't cover everything.

3. You have an error which does not appear in any documentation. You search on forums and with google, and then you post.

4. You have a brilliant linuxer friend/relative/whatever who loves talking about Linux. Well, it's always easier to ask such a person. But only if he likes what he's doing, or he might say "no" when you least expect it...

And there are much more cases.

But, one thing I can say. There is a lot of documentation, and it can get you up and running with Linux in only a few days if you're willing to learn. There is no lack of documentation, there is just lack of willingness... But that's just my oppinion...

Originally Posted by Valkyrie_of_valhalla You forgot online tutorials

Thanks. We can include those under "forums".

The man pages have always been my first recourse when trying to figure something out. They've always done well by me.

Why thank you, marietechie, for paying attention to my post! Your snip brings it slightly out of context, so I definitely recommend anyone to read the full post. It's not that long, really.

- The first place I like to go is to the very terse man pages. For a single command I'll generally try different options for that command until I get the results I want. I find that I'll learn more about the command by watching its actions while I'm tinkering with it.

- For larger stuff, such as configuring a server, I'll google for information or tutorials.

- If whatever I've found so far hasn't helped enough, the next place to go is the forums.

- If the forums don't help ... I drop-kick my computer into tomorrow. Tomorrow I will put the pieces back together and try again!

This depends on what the problem is.
If it's trying to understand how to use a command, then I'll go through the man pages, then check the web, then post here.
If it's a problem that I can't get my head around, then my first stop is google, then here at LQ.org

I voted for Forums, because that's where I get the vast majority of my help.

I love google, I'll often google my problem first and if I don't find the quick answer, I'll read the man page. Often times, I'll read a man page online because it's easier to read then in a terminal.

Well here is my experience. When i started with linux i couldnt even boot into it so man pages would not have done me any good. Googleing didnt help. So my final result was to come here and ask. THat problem got resolved fairly quickly. Since then most of my problems couldnt be resolved through man pages, not that i even knew that they existed at the time. And now that i know about the man pages, i have used them, but have found them alot of the time to be fairly useless.They told me aobut the command and told me what the options were. If i didnt know what exactly i was looking to do then knowing what the options are do me no good. They may be great for explaining commands, but they arent the best for configureing or telllign yo what options you need, like if you need to install a software.

Originally Posted by short circut They told me aobut the command and told me what the options were. If i didnt know what exactly i was looking to do then knowing what the options are do me no good. They may be great for explaining commands, but they arent the best for configureing or telllign yo what options you need, like if you need to install a software.

You make a good point here. There is a sort of catch-22 with the man pages. Man pages try to explain how to use a particular package. But in my experience you do have to install the package for the man page to become available for reading. So you will generally need to resort to some outside assistance for the initial installation. "What came first, the chicken or the egg?"

I think a big part of the problem here is that a lot of people who write man pages never learned to write.

Also, the authors seem to think that the people reading them are already "experts". The stereotypical geek that can't speak to a "normal person" -- who is exactly the person needing those man pages the most!

That said, man pages are generally useful for a simple command when you already know what you want to do. Someone else said they tell you what to do, but not why. That's not even the case (usually).

They tell you what you can do -- but generally don't even help you pick the "what". Also, options are listed with "what" they do, but the user does not often know what any of those settings even are.

Of course, this depends on the program. I go to the man pages, but they are generally not useful for anything complicated. They also may not be complete.

Like others, I read the man pages. Sometimes I Google then go to a forum, but usually it's the opposite, if only because the most useful Google pages point back to various forums, anyway. But really, in most cases, whether you Google before or after checking forums seems to be irrelevant -- as long as you do both. Of course, Google also points up "posts" made to websites and blogs as opposed to forums.

I should also say that non-experts are naturally going to be less effective in their searches. It's not that we don't search, it's that it's often not until we get feedback from more knowledgable users that we have enough information to search more effectively!

As for Distribution Docs, they are useful for basic installation instructions and lists of packages and features, but when you run into a problem, they are rarely the place to go because the problem likely depends on your specific hardware.

So, I voted Forums #1, but that does not imply that I don't use Google and man pages. I imagine the same is true (I hope) of most of us.

I think a big part of the problem here is that a lot of people who write man pages never learned to write. Also, the authors seem to think that the people reading them are already "experts". The stereotypical geek that can't speak to a "normal person" -- who is exactly the person needing those man pages the most!

Exactly. The only times I dip into man pages is when I need to find out the meaning of this or that specific option. Quite a few are so terse that they border on complete meaningless at some stage. It wouldn't be the first time that I hoped someone would write a man page for a specific man page. Not to mention that they look and feel incredibly outdated.

Plus: relying on man pages is one of the surest means to get many newbies complaining that they can't see the trees for the forest. Man pages do not offer a well-rounded picture of what a Linux system can do unless you already know what it can do and you just need some clarification. Frankly, I wouldn't be half as productive if I hadn't spent some time studying books and online tutorials.

Yes, that's true.

Also, you can't look up errors in man pages. You use man pages when you want information on a specific command. You come to a forum to Search + also Google when you have a problem with your system or app.