John Smith's Blog

Ramblings (mostly) about technical stuff

Man pages are not optional

Posted by John Smith on

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: Screengrab of the unhelpful output of 'man puppet'

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.

About this blog

This blog (mostly) covers technology and software development.

Note: I've recently ported the content from my old blog hosted on Google App Engine using some custom code I wrote, to a static site built using Pelican. I've put in place various URL manipulation rules in the webserver config to try to support the old URLs, but it's likely that I've missed some (probably meta ones related to pagination or tagging), so apologies for any 404 errors that you get served.

RSS icon, courtesy of www.feedicons.com RSS feed for this blog

About the author

I'm a software developer who's worked with a variety of platforms and technologies over the past couple of decades, but for the past 7 or so years I've focussed on web development. Whilst I've always nominally been a "full-stack" developer, I feel more attachment to the back-end side of things.

I'm a web developer for a London-based equities exchange. I've worked at organizations such as News Corporation and Google and BATS Global Markets. Projects I've been involved in have been covered in outlets such as The Guardian, The Telegraph, the Financial Times, The Register and TechCrunch.

Twitter | LinkedIn | GitHub | My CV | Mail

Popular tags

Other sites I've built or been involved with

Work

Most of these have changed quite a bit since my involvement in them...

Personal/fun/experimentation