cbannis...@slingshot.co.nz schreef op 29-12-2016 14:44:
[sorry for the late response.]
On Fri, Nov 18, 2016 at 11:05:48AM +0100, Thomas Schmitt wrote:
It is not easy to describe a program with many use cases and even
more particular settings and actions.
What lacks to my experience as confused reader and as best effort
writer
is the user's view on the programs. man pages should document the
details
and often do sufficiently.
But the user looks for solutions, not opportunities.
An interesting thing to ponder is whether a tractor manual should
explain
how to prepare a field to plant carrots.
Also, think of man pages as a reference (what does that switch do
again?)
not as a "first introduction" or tutorial.
e.g. I'd be annoyed if a chess database program's documentation
consisted of
how to play the game, rules of the game, etc.
I have heard that analogy before but it's really off.
That's not what people are asking for.
I was arguing with an OpenSUSE person about the completness of the
sendmail (from exim?) manual page.
The man page was actually ripped from their complete manual. Yet he
called it complete. I should say that the other way.
He considered it "complete". Yet it was actually just a fragment
actually "ripped" from the entire manual, that just described the
command line syntax / parameters.
By its very definition, that could not be a complete man- page.
Well it could be a complete man /page/ I guess, just not a complete
manual...
The "man" system is supposed to resemble a book.... with sections, and
pages for every command...
But when you take a real manual and rip a small part out of that, ....
it can never be considered complete unto itself.
Anyway.
The problem is that the info system and /usr/share/doc are not
accessible in the same way that the man system is accessible. I would
consider both info and /usr/share/doc to be so inaccessible it does not
even come near the man system. So the man system is really the only
functional element the system has.
After man comes not info or /usr/share/doc but... searching the web for
the complete manual or documentation. THAT is the systems we have.
I just want to say I agree completely here with Thomas Schmitt but I
just subscribed to the list and don't have those messages, so can't
reply to those individual ones.
Some man pages do reasonably well but others do very bad indeed often
even lacking good examples of usage.
Man is often the first step in learning about a program. It is not
really a reference guide, although it has to be concise and quick to
read.
If you think "man" is just reference guide, you misunderstand the
position it has in the system.
It particularly has to come down to business real quick. Get down to
business I mean. But that means providing a user with the most common
use case quickly and more pheripheral options can wait. It also means
giving quick examples. Man is all about speed. If I don't want speed I
will search the web for a manual of sorts.
The absolute poorest man page I have ever seen is that of "aufs". The
best... there are many good ones? "grep" is good. Many of the most
common utilities have pretty good man pages.
But if you are going to say the purpose of a man page is to be a
complete reference guide unto its options, then you will write dirt poor
man pages. That is all I can say here.
