Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal")
[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
Reply to: