Half a century after its creation, the Unix manual page format remains a good template for technical documentation and more.
Database sections
Only needed for actual man pages meant to be installed on a Unix system. (But worth keeping in mind anyway.) The section number is used as file extension in that case.
Sections 5, 6 and 7 are of general interest, as they go beyond the technicalities of an operating system.
1. User commands
Of interest to anyone with an account on the system.
2. System calls
For low-level kernel stuff(?)
3. Library calls
Mostly for C, Perl and Tcl.
4. Special files (devices)
Advanced OS usage.
5. File formats and configuration files
Apparently intended for reference documentation. Overviews and such should probably go in (7) below.
6. Games
Doesn't have to be computer games. For example Risus, "the anything RPG", can be easily made into a manual page.
7. Overviews, conventions and miscellaneous
On Linux, manual page guidelines are documented in man-pages(7); on NetBSD, they're in mdoc(7) instead.
8. System commands
For administrators.
Section headers
This document only includes section headers used in most manual pages, not only for commands and/or functions. The list can be added to or trimmed, but standard sections used at all should appear in order and with these names.
Subsections are allowed, but the number of levels should be kept minimal.
NAME (mandatory)
Subject - one-line description after a dash
SYNOPSIS (mandatory)
Can list multiple commands or whatever as one logical group.
DESCRIPTION (mandatory)
Doesn't have to be long or detailed.
OPTIONS
Best interpreted loosely. For example, in a tabletop RPG optional rules can go here.
FILES
For software, this means files used by the program during normal operation, such as config and so on. Other kinds of projects will require creativity.
NOTES
Exactly that.
BUGS
Arguably makes sense only for software. Or does it?
EXAMPLES
Just enough to get people started with common use cases.
AUTHORS
Linux documentation guidelines say not to use this. Obviously that doesn't apply to other projects. Contact information goes here.
COPYRIGHT
For licensing and ownership information(?)
SEE ALSO (mandatory)
Lists other manual pages normally, but might need to be interpreted flexibly in some cases.
How to make Unix manual pages
- Write as Perl POD, convert with
pod2manandpod2html. The latter in particular emits very clean markup. - Write as AsciiDoc, convert with the eponymous tool or else AsciiDoctor.
- For Python modules, the
pydoc/pydoc3tool generates documentation in a very similar format.
Notes
- Many if not most Linux manual pages follow guidelines poorly if at all.