On Fri, Nov 18, 2016 at 11:05:48AM +0100, Thomas Schmitt wrote:
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.
I once spoke to the autofs developer about the difficulty of
understanding how to use the system.
There were two elements to the confusion:
a) The developer admitted that he had no clue how a user would look at
his system because he had been ingrained into and embedded into it for
so long. He did not know how an outsider would look at it or would or
would not understand.
b) Not everyone is so keen on the numeric sections (5, 8, etc.) and it
can quickly elude you if you are not trained to take note of it. An
important man page, quite an essential man page, eluded me for quite
some time because it was named the same as an other man page with the
same name in a different section, that superseded the other one.
So at least two lessons to learn from this you know:
- give all your man pages a different name (not just different section
number)
- you must approach your man page as a new user. Someone who doesn't
know anything. And also: developers can lose track of what they program
looks like to the outside.
I think by "solutions" Thomas means that the program provides a certain
base functionality. This will agree with several succinct use cases.
Those use cases can be taken as the starting point on how to detail the
functionality. This means "I want to do this, that and that" becomes the
organisation of the man page. The man page will tell you how to do this,
that and that. It is oriented around tasks, not a dispersed list of
options and patterns.
For example the "apt" man page (on Debian Jessie) is oriented precisely
around tasks. It is too short to really be useful and doesn't even list
all the options it has, but it is an example of a task-oriented layout.
Apt-get does the same and is probably a very good man-page. So it is not
even out of the ordinary here. Some people just don't "get" it.
