Earlier this year, I described three important characteristics of good documentation: concise, consistent, and simple. Good word choice, I wrote, is important for understanding and translation. But that doesn't mean it has to be dry and boring.
Want to know a secret? My favorite tech books to read are the For Dummies books. Like many of you, I have a fair number of O'Reilly books on my shelf and they are excellent. I've learned much from the serious tech books I own, but when I need to sit down with an unfamiliar subject and learn, the humorous books are what hold my attention. If you want me to pay attention to your documentation, the best way to keep my interest is a liberal use of "Airplane!" references. Looks like I picked the wrong week to quit sniffing [binding] glue.
It's okay, even beneficial, to let your project's personality get into the documentation, but there are some caveats. Be aware of colloquial expressions that don't make sense in another language, or even in another dialect of the same language. Know that your witty pop culture reference might get missed, or not be considered funny (yes, there are even people who don't like "Airplane!"). The goal is not to try to be funny, but to allow your own style. As Bob Reselman told Rikki Endsley in an interview about his SCaLE 14x talk: "dry sucks."
But as with most things in life, there are exceptions. Dry is great for reference materials: API documentation (though feel free to be yourself in examples), glossaries, and release notes.
Think about the kind of documentation you like to read, and write that. If people don't like it, you can be sure they'll let you know.
7 Comments