[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. -- The media's the most powerful entity on earth. They have the power to make the innocent guilty and to make the guilty innocent, and that's power. -- Malcolm X
