Technical documentation doesn't have to be dull

2 readers like this
2 readers like this
Technical documentation doesn't have to be dull

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.

Ben Cotton is a meteorologist by training, but weather makes a great hobby. Ben works as the Fedora Program Manager at Red Hat. He co-founded a local open source meetup group, and is a member of the Open Source Initiative and a supporter of Software Freedom Conservancy. Find him on Twitter (@FunnelFiasco) or at


I agree. Humor is the key to holding my attention too.

I agree, but while translating manuals for OpenSource projects, I learned: Let's not forget that humor is _very_ difficult if not impossible to translate, as language always has a specific geographical, social or other background...

In reply to by Don Watkins

Jan, that's an excellent point. So much of humor is cultural, so it can be tough to translate. If you have some advice on how to strike that balance and how translators can try to preserve the tone while localizing the joke, I think that would make a great Doc Dish article.

In reply to by Jan Niggemann

If nothing else, people should write documentation in a more conversational tone. Not rambling, but concise and friendly. That goes a long way to keeping readers interested. I've tried that, with mixed success, at various technical writing jobs I've had over the years. I have a feeling that it's easier to get members of an open source project on board with that rather than trying to convince staid business types of the benefits ...

As with almost anything, one can say that there are good For Dummies books and not so good or even irritating For Dummies books. In some of them, the idiosyncratic attempts at humor get progressively irritating.
Having helped write a 400+ page manual for Scribus, I know that this aspect is very challenging. For that, we tried to lighten it up when we could, and sometimes this can come from the photos you choose in illustrations, but we also made an effort to have a consistent style of writing.

Any attempt to be other than deeply boring in technical writing for business is almost certain to be shot down as "unprofessional". Open Source shouldn't feel the same constraint.

Useful real-life examples are always good. Some of the best documentation I've ever encountered was for Borland's Turbo C++. A lot of the sample code could be lifted and used verbatim.

Creative Commons LicenseThis work is licensed under a Creative Commons Attribution-Share Alike 4.0 International License.