[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.