Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal")

[Catherine Gramze <rhiamom@gmail.com>]

On Thu, Dec 29, 2016 at 1:36 PM, Xen <list@xenhideout.nl> wrote:

More importantly the man system or man format does not preclude such documents being written as tutorials so basically it is being done all around.

So your assertion here does not really have a basis in reality I must say: the system does not preclude this from being done. People can do it all they want, and they do it.

It is the people that insist on not doing it, that write poor man pages.

​I did not say the man page system precluded it, nor that no man page was written in such a manner. I stated the original purpose and design of the man page as a complete reference, and only a reference, and the futility of wishing that all man pages would be re-written to conform to your personal preferences.​ What you apparently consider to be a "poorly written" man page I find to be highly accessible and useful. Give me the command and the list of options, with a sentence or so explaining the function of each option. Done. I can figure out which options I need better than somebody not in my situation. Examples muddy up the page and make it harder to scan the options for what I need without adding any clarity to the function..