cbannister@slingshot.co.nz schreef op 29-12-2016 14:44:
[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 detailsand often do sufficiently. But the user looks for solutions, not opportunities.An interesting thing to ponder is whether a tractor manual should explainhow 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 ofhow to play the game, rules of the game, etc.
I have heard that analogy before but it's really off. That's not what people are asking for.I was arguing with an OpenSUSE person about the completness of the sendmail (from exim?) manual page.
The man page was actually ripped from their complete manual. Yet he called it complete. I should say that the other way.
He considered it "complete". Yet it was actually just a fragment actually "ripped" from the entire manual, that just described the command line syntax / parameters.
By its very definition, that could not be a complete man- page.Well it could be a complete man /page/ I guess, just not a complete manual...
The "man" system is supposed to resemble a book.... with sections, and pages for every command...
But when you take a real manual and rip a small part out of that, .... it can never be considered complete unto itself.
Anyway.The problem is that the info system and /usr/share/doc are not accessible in the same way that the man system is accessible. I would consider both info and /usr/share/doc to be so inaccessible it does not even come near the man system. So the man system is really the only functional element the system has.
After man comes not info or /usr/share/doc but... searching the web for the complete manual or documentation. THAT is the systems we have.
I just want to say I agree completely here with Thomas Schmitt but I just subscribed to the list and don't have those messages, so can't reply to those individual ones.
Some man pages do reasonably well but others do very bad indeed often even lacking good examples of usage.
Man is often the first step in learning about a program. It is not really a reference guide, although it has to be concise and quick to read.
If you think "man" is just reference guide, you misunderstand the position it has in the system.
It particularly has to come down to business real quick. Get down to business I mean. But that means providing a user with the most common use case quickly and more pheripheral options can wait. It also means giving quick examples. Man is all about speed. If I don't want speed I will search the web for a manual of sorts.
The absolute poorest man page I have ever seen is that of "aufs". The best... there are many good ones? "grep" is good. Many of the most common utilities have pretty good man pages.
But if you are going to say the purpose of a man page is to be a complete reference guide unto its options, then you will write dirt poor man pages. That is all I can say here.