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

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

The thread and the responses by Catherine Gramze is one example of that. She defends bad writing. She comes up with all kinds of excuses as to not want to explain anything. Saying it is Good to not explain stuff.

If you are going to say it is Good not to explain stuff, BAD WRITING WILL ENSUE.

So if there is a dearth of good writers, it is because there is an overabundance of bad attitudes. To writing. You try to convince me that explaining stuff to new users is bad because you want your man pages to be reference only material.

That is something only a bad writer would say.

And anyone saying that would become a bad writer.

Ad hominem attacks now, Xen, since you cannot refute the simple fact that man pages were designed to be a reference, not a tutorial?

My university technical writing course professor would disagree with your evaluation of my writing ability. He saved my work to use as examples for future classes of what he wants to see in technical writing. And I am a programmer, too, one of a very few selected by a professor to work in his IT consulting firm while still in grad school. Yes, some people can both write and code.

If you do not know what a command basically does, a man page is not the place to go. I am not familiar with aufs, but I learned from the example of "bad writing" you posted that it is a filesystem utility, that it loads things in a specific sequence that has to be kept in mind when using the command, and that you wanted your specific solution laid out for you in the man page instead of figuring it out yourself.

Linux has come a long way since I first began using it in 1997; its users are no longer limited to programmers and fearless non-programmers. That is what the development of gnome and KDE were for, the non-programmers to make it easy. Those users were never expected to look at a man page. If you are looking at a man page you are doing non-trivial non-noob things and should abandon the noob mindset.