Operation Cheerful: Clarity expendable

As I'm reading Philip Grenspun's why most computer books suck, I can't help but draw a big smile. This is exactly how we had to write documentation and tutorials at my old job. Keep the cheerful spirit up at all costs. Clarity expendable.

Saving developers hours of frustration was not an option, if it detailed admitting the product was flawed in any way. The poor programmer using our software (a collection of community tools) had to learn all it's quirks, of which there were many, the hard. We knew perfectly well where the software sucked, but couldn't tell.

This prioritation was enforced by documentation reviews where presetation was king, technical details the starved peasant. Reviews were conducted not by the developer's peers, who would actually be able to provide meningful feedback, but by a manager far removed from the code. The result? Documentation that obeyed the rules of grammar, but failed to do customers much good.

That developers reading the documentation wouldn't have any thing to do with the purchase decision, the only justification I can think of, however falliable, seemed lost on the management.

Good documenters works by teaching programmers how to make the most of the software in the least amount of time. Everything else is a distant second.