discuss: man pages
Subject:
Re: man pages
From:
"Anthony E. Greene" ####@####.####
Date:
16 May 2003 11:59:47 -0000
Message-Id: <3EC4D381.2030202@pobox.com>
Rahul Sundaram wrote:
> just bcoz u like scrolling up with those keys dont
> assume everyone will do so. the power of linux
> shouldnt scare people of. ls can have umpteen
> options.i am not against that but i want the relevant
> ones first in a help page.is that bad?
What are "relevant" options? How is the documentation author supposed to
know which options you think are relevant? The options are all there. the
user just needs to read or search to find what they need.
If users expect to look at web pages, they need to know how to navigate
around in a browser. If they expect to look at man pages, they need to
know how to navigate around using their pager (probably 'less' on Linux).
On GNOME and KDE systems, they can use the file manager to view man, info,
and HTML pages in an interface that should be easily usable to any GUI user.
Generally man pages are for reference, not for inroducing newbies to a new
tool. Web pages and HOWTOs are spcifically designed for that. But most
people are only newbies for a relatively short period over the life of the
time they use Linux. Redesigning all the docs for that short period is
simply not reasonable. Most people quickly learn that man pages are
(mostly) not the place to look for detailed explanations and examples. I
spent a few months figuring out the best places to find docs and how to
use the basic tools. After that, I spent more than 5 years using Linux
daily. rewriting the man pages for those few months would have resulted in
me having to read newbied docs for the next five years.
There are docs for learning, and there are docs for using. That is a good
design.
What would be good is an easily findable way for new GNOME and KDE users
to find tutorial docs on their local system. That is a desktop and
distribution issue though. The LDP should stay focused on providing good
tutorial and cookbook docs. Trying to create a whole new set of docs is
not practical, for a whole slew of reasons. This would basically involve
changing an established standard way of doing things.
As widespread as the GNU utilities are, I don't know anyone who routinely
uses the GNU info pages instead of the established man pages.
What you're talking about is a huge project. Huge. And the proposed
benefit is to make it easier during the first few months.
There are ways to accomplish that that do not involve a complete redesign
of the Linux documentation system.
Tony
--
Anthony E. Greene ####@####.####
OpenPGP Key: 0x6C94239D/7B3D BD7D 7D91 1B44 BA26 C484 A42A 60DD 6C94 239D
AOL/Yahoo Chat: TonyG05 HomePage: <http://www.pobox.com/~agreene/>
Linux. The choice of a GNU generation. <http://www.linux.org/>
