How to write documentation in the style of qmail

[cdybedahl]

1) Write down 90% of all relevant information, one piece of it per line.

2) Randomize the order of the lines.

3) Divide the resulting mess into manpages.

4) Sprinkle with SEE ALSO sections that point at randomly chosen other pages.

5) When somebody complains that the documentation is fucking useless, just state that all the information is in there.

Comments

Not just me, then

[sugoll.livejournal.com]

I moved over to qmail a year or so ago, and gave serious consideration to hacking the sources for a few things.

The main things that annoy me at present are:
- a local process can't connect to the local daemon and send mail to a remote host, unless the remote host is in a whitelist. I.e. you have to know to whom you'll be sending mail.
- the local alias expansion doesn't update the headers. You mail to "bob", which is aliased to "bob@example.com", and the outgoing mail gets sent there, but still has just "bob" in the headers; relay hosts have a tendency to "fix" this en route with their own local domains...

[khrister.livejournal.com]

When I read stuff like this, I'm grateful that we chose postfix...

Not that postfix is all hugs and puppies, but generally the man pages talk about what they're supposed to, are coherent and in many cases even correct.