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!
Richard WM Jones 
Yes, Perl and POD is great. Very easy.
The next step up the ladder is “asciidoc” which also seems to do a great job converting easy text markup to man pages.
http://www.methods.co.nz/asciidoc
Alastair
I’ve used asciidoc to write several (well, two) documents, and I’m not convinced. I’m not saying it’s not good, but I don’t think it’s as good for writing Unix man pages specifically. It may be a matter of personal preference, but I didn’t like how asciidoc-generated man pages and HTML pages looked.
I will say though that asciidoc is simple and expressive.
Pingback: Man page for transmision-remote-cli « Yevlempy’s Blog
Pingback: WTFM (Write the Fine Manual) with Pod2man text-converter | Linux Tidbits