LinuxQuestions.org
Visit Jeremy's Blog.
Go Back   LinuxQuestions.org > Forums > Non-*NIX Forums > General
User Name
Password
General This forum is for non-technical general discussion which can include both Linux and non-Linux topics. Have fun!

Notices

View Poll Results: Which documentation do you use most?
Help Files 12 57.14%
Forums 5 23.81%
Mailing Lists 0 0%
Books 3 14.29%
None - I ask a friend/co-worker/family member for help. 0 0%
None - I figure it out on my own. 1 4.76%
Voters: 21. You may not vote on this poll

Reply
 
Search this Thread
Old 08-08-2007, 01:26 PM   #1
marietechie
Member
 
Registered: Feb 2007
Distribution: Mandriva 2008 (KDE)
Posts: 71

Rep: Reputation: 15
Man Pages in Linux: Your Experience?


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

SlowCoder states:
Quote:
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.

Last edited by marietechie; 08-08-2007 at 01:38 PM.
 
Old 08-08-2007, 01:33 PM   #2
alred
Member
 
Registered: Mar 2005
Location: singapore
Distribution: puppy and Ubuntu and ... erh ... redhat(sort of) :( ... + the venerable bsd and solaris ^_^
Posts: 658
Blog Entries: 8

Rep: Reputation: 31
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 ...


.
 
Old 08-08-2007, 01:38 PM   #3
rshaw
Senior Member
 
Registered: Apr 2001
Location: Perry, Iowa
Distribution: Mepis , Debian
Posts: 2,694

Rep: Reputation: 45
i think people expect too much from man pages. they are there to tell you 'how' not 'why'.
 
Old 08-08-2007, 01:43 PM   #4
rocket357
Member
 
Registered: Mar 2007
Location: 127.0.0.1
Distribution: OpenBSD-CURRENT
Posts: 476
Blog Entries: 117

Rep: Reputation: 74
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".

Last edited by rocket357; 08-08-2007 at 02:28 PM.
 
Old 08-08-2007, 02:17 PM   #5
Valkyrie_of_valhalla
Member
 
Registered: Jan 2006
Location: Romania
Distribution: Suse 12.0, Slackware 12.1, Debian, Ubuntu, Gentoo
Posts: 301

Rep: Reputation: 30
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...
 
Old 08-08-2007, 02:23 PM   #6
marietechie
Member
 
Registered: Feb 2007
Distribution: Mandriva 2008 (KDE)
Posts: 71

Original Poster
Rep: Reputation: 15
Lightbulb

Quote:
Originally Posted by Valkyrie_of_valhalla
You forgot online tutorials
Thanks. We can include those under "forums".
 
Old 08-08-2007, 02:35 PM   #7
masonm
Senior Member
 
Registered: Mar 2003
Location: Following the white rabbit
Distribution: Slackware64 13.37 Android 4.0
Posts: 2,248

Rep: Reputation: 46
The man pages have always been my first recourse when trying to figure something out. They've always done well by me.
 
Old 08-08-2007, 02:40 PM   #8
SlowCoder
Member
 
Registered: Oct 2004
Location: Southeast, U.S.A.
Distribution: Fedora (Desktop), CentOS (Server), Knoppix (Diags)
Posts: 934

Rep: Reputation: 38
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!
 
Old 08-08-2007, 03:19 PM   #9
hacker supreme
Member
 
Registered: Oct 2006
Location: As far away from my username as possible
Distribution: Gentoo
Posts: 259
Blog Entries: 1

Rep: Reputation: 30
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.
 
Old 08-08-2007, 03:27 PM   #10
drac0
Newbie
 
Registered: Sep 2005
Posts: 0

Rep: Reputation: 0
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.
 
Old 08-08-2007, 04:00 PM   #11
short circut
Member
 
Registered: Jun 2006
Distribution: Fedora Core, and Gentoo eventually, but i hate (XKEU)buntu
Posts: 48

Rep: Reputation: 15
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.
 
Old 08-08-2007, 04:12 PM   #12
SlowCoder
Member
 
Registered: Oct 2004
Location: Southeast, U.S.A.
Distribution: Fedora (Desktop), CentOS (Server), Knoppix (Diags)
Posts: 934

Rep: Reputation: 38
Quote:
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?"
 
Old 08-08-2007, 04:35 PM   #13
ShellyCat
Member
 
Registered: Jul 2007
Distribution: Slackware 13
Posts: 178

Rep: Reputation: 28
Man pages are passable-to-very-good, depending

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.

Last edited by ShellyCat; 08-08-2007 at 04:37 PM.
 
Old 08-08-2007, 04:48 PM   #14
jay73
Guru
 
Registered: Nov 2006
Location: Belgium
Distribution: Ubuntu 11.04, Debian testing
Posts: 5,019

Rep: Reputation: 130Reputation: 130
Quote:
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.

Last edited by jay73; 08-08-2007 at 04:50 PM.
 
Old 08-08-2007, 06:14 PM   #15
ShellyCat
Member
 
Registered: Jul 2007
Distribution: Slackware 13
Posts: 178

Rep: Reputation: 28
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.
 
  


Reply

Tags
documentation


Thread Tools Search this Thread
Search this Thread:

Advanced Search

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is Off
HTML code is Off


Similar Threads
Thread Thread Starter Forum Replies Last Post
transfer aix man pages to linux zefo AIX 3 02-15-2007 03:08 PM
Linux man pages apostrophe problem??? Ynog Linux - General 1 01-07-2004 02:34 PM
Linux MAN Pages in PDF format SolarDegree Linux - Newbie 5 03-23-2003 01:01 PM
Linux MAN Pages in PDF format SolarDegree Linux - General 1 03-23-2003 07:53 AM
Man Pages (Linux 7.2) -- Disappeared rbooker Linux - General 1 10-24-2002 01:41 PM


All times are GMT -5. The time now is 09:50 AM.

Main Menu
My LQ
Write for LQ
LinuxQuestions.org is looking for people interested in writing Editorials, Articles, Reviews, and more. If you'd like to contribute content, let us know.
Main Menu
Syndicate
RSS1  Latest Threads
RSS1  LQ News
Twitter: @linuxquestions
identi.ca: @linuxquestions
Facebook: linuxquestions Google+: linuxquestions
Open Source Consulting | Domain Registration