I write quite a bit of code in Perl, and more in C, OCaml and other strange languages, but for writing man pages there’s one thing I always use: POD.
Although POD comes from a Perl background, you can really use it to document any program. All you need is a “foo.pod” file starting with this template:
=encoding utf8 =head1 NAME foo - Foobar your bazfiles =head1 SYNOPSIS foo [bazfile] =head1 DESCRIPTION Write your description here. Use B<for bold>, I<for italic> and C<for inline code>, and a blank line to separate paragraphs. =head1 SEE ALSO L<bar(1)>, L<baz(5)>
See perlpod for the full markup, but the advantage of POD is the markup is deliberately limited and simple.
As well as turning your POD file into a manpage using pod2man, you can also turn them into web pages. The default look for POD-generated web pages is pretty sucky. Nevertheless with only a tiny bit of styling you can make them look great, which is how I make all the libguestfs web pages. Examples: guestfish(1), guestfs(3).
The only thing I haven’t worked out yet with the web pages is how to get inter-manpage links to work properly.
Nevertheless … POD is great and simple. Use it!