On Sat, Dec 24, 2011 at 10:08:31AM EST, Bill Gradwohl wrote: [..]
> The man page is written the way Robbie the Robot used to speak in the old > black and white TV days¹. Short, cryptic and in many cases unintelligible IN > THE DETAILS. Alternatively, one might snicker that some lawyer wrote it to > purposely make it difficult to understand. As with most of the > documentation I've seen in the Linux community, it's awful. [..] I find it rather ironical that your rant should amount to a clumsy rewording of section 6.1, GNU Manuals, from the GNU Coding Standards: http://www.gnu.org/prep/standards/html_node/GNU-Manuals.html#GNU-Manuals In particular: ‘Don’t use Unix man pages as a model for how to write GNU documentation; most of them are terse, badly structured, and give inadequate explanation of the underlying concepts.’ CJ ¹ Actually, regarding form rather than content, man pages go back considerably farther than Robbie the Robot and black and white TV... some 2,000 years or so... See wiki articles, re: ‘scrolls’ and ‘codex’ for the details.
