On this day in 1971 the first version of the Unix Programmer's Manual was published.
- 
On this day in 1971 the first version of the Unix Programmer's Manual was published. This included the first ever man pages.
 - 
On this day in 1971 the first version of the Unix Programmer's Manual was published. This included the first ever man pages.
I like a good man page. As reference documentation for command line programs and such, they can be really good. "What does foo do? I'll run 'man foo' to see. Oh! That's useful!" should take at most seconds.
Most man pages aren't good. They're long, don't follow conventional structure, are badly formatted, lack examples, are written for the author and not the reader. Every time I open a man page that starts with a BNF syntax specification for the command's CLI I despair.
 - 
I like a good man page. As reference documentation for command line programs and such, they can be really good. "What does foo do? I'll run 'man foo' to see. Oh! That's useful!" should take at most seconds.
Most man pages aren't good. They're long, don't follow conventional structure, are badly formatted, lack examples, are written for the author and not the reader. Every time I open a man page that starts with a BNF syntax specification for the command's CLI I despair.
Writing a good man page is mostly about producing clear technical writing and following conventions. Conventions are important: they enable readers used to manual pages to look up things very quickly. Convention covers both structure (NAME, SYNOPSIS, DESCRIPTION, EXAMPLE, etc) and formatting.
See the man-pages page in section 7, at least on Debian-style distributions.
The incidental details of markup languages, tooling, etc, are often annoying, and frustrating, but not hard as such.
 - 
undefined Oblomov shared this topic 
undefined Maronno Winchester :antifa: shared this topic