Man pages are not optional
Spent a few hours today playing with Puppet, which I'd been meaning to have a look at for ages.
I followed a beginner's tutorial, which didn't work - Puppet failed to stop or start ntp in the way the tutorial describes. In and of itself, this didn't bother me - in fact, I often find it useful when things screw up, as it forces you to start digging in and investigating, at which point you start learning how things really work.
What was a bit annoying though, was the lack of any obvious warnings or errors, either in the output, or in the log files. (Puppet logs to both /var/log/messages and files in /var/log/puppet/, but the former had nothing useful, and the latter just contained incomprehensible HTTP request URLs.)
Never mind, I thought, I'll just check the man page. This is what I got:
It doesn't look to be an issue specific to my distro either.
I don't give a damn how good any project's online documentation is; something that is going to be interacted with from a *nix command line - especially when aimed at a system admin audience - should have a manpage that at least covers some of the basics in a modicum of detail. I don't care for the GNU stuff that pushes you towards the info command that I've never seen anyone actually use, but compared to Puppet, they're wonderful.
Obviously Unix manpages are far and away from being the new hotness, and the lack of stuff like proper hyperlinks is a bit annoying in this day and age, but the fact that they have survived this long shows how useful they are. If the author(s) of a tool can't be bothered to spend a few hours putting together a half-decent manpage, then I'm not sure I feel inclined on spending any time bothering to research and learn that tool.
EDIT: I've just seen that you can do puppet describe {string} to get something that's roughly comparable to a proper manpage, just inferior in pretty much every respect. (e.g. no nice formatting on a terminal that supports bold or underline, having to pipe into more/less/etc if you want to page it) Too late though, I'm moving on...
EDIT#2: On further investigation, I'm not sure what puppet describe or puppet doc actually do, but it's certainly not providing docs about the subcommands such as "agent", "apply", "cert", etc as mentioned in the manpage.