On 22.09.14 13:31, Gregg Eshelman wrote: > Instructions that assume prior knowledge of something, or do not have > pointers as to where else in the instructions (or online) all required > information can be found are often not much better than no instructions > at all.
Traditionally, most manpages are not tutorials - they all require a threshold level of understanding for them to be of much use. And they very often minimally document _how_ to invoke stuff, barely alluding to _what_ that might be good for. I remember in the early days, cycling through the manpages in "SEE ALSO" on many a unix manpage, in order to gain sufficient overview to try some experiments, in order to clarify my understanding of the command's many option combinations. After a few decades, it does seem infinitely easier. Even the on-line manual embedded in vim can be remarkably inscrutable, despite the fact that it _is_ example-rich and full of detail, simply because we only know the best search keyword once we know at least half the solution to the gaping lack of knowledge which initiated the search in the first place. Mutt is in a similar boat; a very detailed linked manual, full of wonderful information - but all of it hidden by our ignorance of the right keyword to take us straight to the thing we want to do. On the other hand, it often does not occur to the guru creating the manpage to document stuff which is dead obvious after just having finished coding the relevant service or module. That's where we users come in - we can whip up an explanatory paragraph or two when a documentation omission has been explicated. As for "pointers as to ... all required information", I suspect that our doughty¹ developers are thinking "Use the wiki, Luke.", after all, that is the "pointers as to ... all [available] information" Erik ¹ Used here not only in the sense "Able; strong; valiant; redoubtable;", but also Danish dygtig (skilful). -- Tragically, Liberia - which already ranks fourth-last in the world for numbers of doctors per population - has lost almost 20 doctors to Ebola. They only produce 10 doctors per year in a medical class. - http://www.abc.net.au/news/2014-09-13/australian-doctor-says-time-running-out-to-contain-ebola/5741858 ------------------------------------------------------------------------------ Meet PCI DSS 3.0 Compliance Requirements with EventLog Analyzer Achieve PCI DSS 3.0 Compliant Status with Out-of-the-box PCI DSS Reports Are you Audit-Ready for PCI DSS 3.0 Compliance? Download White paper Comply to PCI DSS 3.0 Requirement 10 and 11.5 with EventLog Analyzer http://pubads.g.doubleclick.net/gampad/clk?id=154622311&iu=/4140/ostg.clktrk _______________________________________________ Emc-users mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/emc-users
