Man pages (was: Setting up a second monitor)

Jean Hollis Weber jean-ooo at taming-openoffice-org.com
Thu Apr 20 22:28:19 UTC 2006


I just got up awhile ago and am working my way through the mail 
that accumulated overnight.

Not to restart a flame war, but as the OP on this thread, I would 
like to say a few things.

Daniel Carrera wrote,
> Antony Gelberg wrote,
>> If you don't know what a BusID is, it's explained in the config file 
>> man page.  If people don't read the manual, things may well look 
>> complicated.

I do read the manual when I know where to look, but I often do
not understand what the manual is telling me. Indeed, reading the
manual often makes a simple process look complicated to me.

> The X config file is, in my honest opinion, quite complicated. Throwing 
> documentation at something complicated doesn't make it less complicated, 
> it makes it well documented.

As a technical writer, I quite agree with that statement!

>> One can always man lspci to find out what the program does.
> 
> Therefore I should never tell people what any command does? Giving a 
> one-sentence description of lspci is helpful. Saying RTFM is (1) not 
> helpful and (2) contrary to the Ubuntu mailing list guidelines.

I would not know lspci from a bar of soap, so a description is
helpful.

>> The OP has been using computers for over 35 years, so let's assume 
>> that he's got something in the brain department.
> 
> Jean is a very intelligent woman, but that doesn't make her a Linux 
> expert anymore than my being an intelligent man makes me knowledgeable 
> of (say) biology. So I try to provide helpful information and offer 
> direct assistance in configuring X.

I really, really appreciate Daniel's (or anyone's) attempts to
translate Linux-speak (and man pages) into plain English.

> Man pages are not meant to introduce a new user to Linux. They are not 
> tutorials, they are reference information for people who are already 
> knowledgeable. The appropriate documentation for new users is not man 
> pages but how-tos and tutorials. It's a different type of documentation.

I completely agree with this statement. As a professional 
technical writer, I have been writing how-tos, tutorials, and 
other new-user documentation for 20 years, and I know that 
new-user documentation is (or should be) *very* different for 
docs aimed at experienced users who need reference material.

Now, back to trying to solve my problem... I've just seen 
Daniel's latest note with some instructions for me, which I will 
follow up on.

--Jean




More information about the ubuntu-users mailing list