Whenever I read an application’s UNIX man page that is much longer than, well, a page, I can’t help but think that it pulled double duty for its author: obligatory storehouse of trivia and (gasp) functional specification.

If you know functional specifications you know how egregious the latter would be. A good one is built on the cornerstone of use cases, i.e. how the application or API in question should behave for the constellation of scenarios. The accompaniment of a configuration wizard is a decent indicator that an application was developed with use cases in mind. The absence of anything more than a serial description of arguments and configuration directives — a.k.a. the man page — is a decent indicator it was not. I’ve said it before and I’ll say it again: 80% of your end-user documentation can be culled from a well-written functional spec.

Detailed use case analyses are mandatory when it comes to security. Without one a sophisticated application is magnetic north for trouble.

If you doubt me try configuring samba relying only on the man page. Mine is 6100 lines, 3966 of them non-blank. You’ll be lucky to get it working let alone innoculated.

Nothing against samba. I chose it at random from large pool of candidates. I’m pleased to say it has some good scenario-based documentation. Just skip the man page unless you’re sure you know what you’re doing.