Historically, I've been accessing documentation as an administrator rather than a programmer. There are a couple of documentation habits that have driven me ha

Historically, I've been accessing documentation as an administrator rather than a programmer. There are a couple of documentation habits that have driven me half mad over the years. * Broken Usage Examples: It's bad enough when an example demonstrating some now deprecated feature hangs around in the introductory text that every new user will cut their teeth on. It's an immediate vote of no confidence when typos or plainly busted syntax makes it into the docs. * Confusingly Abstract Examples: Please no ./foobar -f foo -b bar -i foobar.foo -o barfoo.bar. Just paste an actual usage example, explain it and be done with it. A cousin to this is the use of overly complex "Look how clever I am!" examples. * Explanation By Analogy / Google: Saying things like "configuration files use ____ syntax" without summarizing or at the very least linking to a definitive reference for "____ syntax". * Insane Defaults: This is really a design concern, but if we're already past that point and destructive / poor performing default behavior is the chosen path at least clearly document that fact. --- On a related note, when I'd just started to augment my sysadmin background with code I saved time by writing scripts, small utilities and general automation. As I've learned more, my savings increasingly come from being able to jump into the code to diagnose the odd behavior of poorly documented programs instead of endless profiling, searching and experimentation.