Setting up a second monitor

Jean Hollis Weber jean-ooo at
Fri Apr 21 01:23:46 UTC 2006

Antony Gelberg wrote:
> Is it a fact that man pages are inappropriate for new users or just your 
> opinion?  In my opinion they are useful for any level of user, as are 
> the other types of documentation.  If one wants to understand a config 
> file, a how-to or tutorial may help a little, but really there is 
> nothing as focused or accurate as the man page.

I read the man page for xorg.conf, but it might just as well have 
been written in Swahili for all the good it did me. Forcused and 
accurate? I'm sure it is. Informative? Only as a reference for 
those who already know what it's talking about.

As for "fact" versus "opinion":

I have been a technical writer working on user documentation 
(mainly for a non-technical audience) for over 25 years. If I 
wanted to take the time, I could cite to you numerous studies 
showing that man pages and other reference-type documentation is 
not appropriate for new users, who do not have the background 
knowledge required to understand the information in them. Not 
only that, but the vast majority of new users do not want to 
"understand" a config file or anything else; they just want to 
know what to do to get the job done. Some of them will eventually 
want to understand (not just do) and will seek out the 
information when they are ready for it. Others will not.

In addition to the studies that back up my opinion, here is 
another opinion, also based on long experience: My partner Eric 
has been a Unix hacker for at least 25 years, and he says that 
man pages are not good for *anyone* to learn from; they are good 
for reference material for those who already know what the pages 
are talking about.

> For the OP's task, there is no option but to edit the config file.  If 
> the how-to is not clear, the man page is a good next port-of-call. There 
> is no compulsion for the user to read the entire page as he can just 
> scan it for the relevant sections.

I don't mind editing a config file; I've done that before.

Thank you for the pointer to this page:

It seems to explain things at the right level for me, even though 
the process does seem complicated. It looks like it will give me 
the info I need to edit the config file. I hope so!


More information about the ubuntu-users mailing list