Best practices to put into a man page Best practices to put into a man page unix unix

Best practices to put into a man page


If you cannot find any old bound copies of 1970s Bell Labs "troff" documentation, which had some nice sections on writing man pages, :-) then I'd suggest trying out Jens's "HOWTO" on writing man pages over at his site.


The Unix 7th Edition manuals are available online in a variety of formats.


A BUGS section is nice, and an EXAMPLES section is always useful. Some man pages contain aFILES section which lists related configuration files, or ENVIRONMENT section detailing any influential environment variables.

To be clear, what sections or type of information are useful to users depends on the nature of the program or utility that you are documenting.


There is a canonical man page outline distributed with UNIX systems, or at least usually there is. In general, I'd put in all the fields, and include a line like "none" if it doesn't apply.