The importance of writing to your audience

This is basically a rant, and one that I've alluded to before when discussing the programmer documentation for Qt.

Professor Butts and the Self-Operating Napkin (1931)

Rube Goldberg

Non-trivial software libraries are complex beasts. They have a lot of moving parts. Things have to be done in particular ways. Things often have to be done in particular orders. They may (often do) have abstractions that must be understood. Many require a particular point-of-view on the problem domain to use them well (or indeed at all).

And all this stuff needs to be documented, and that documentation has to be useful to anyone you want to use the library.

If the documentation is written by the author(s) of the library, they face a common problem; I like to call it "the expert's disease".¹ It's the inability to recall what really is basic, simple, and obvious and what only seems that way because you are so familiar with the domain. If you don't know the difference you can write comprehensive and technically accurate documentation (and burn a lot of time on the effort) only to find that isn't of any use to your users even though they are smart and capable programmers.

Well, you find out if you're lucky. Otherwise you ship it in that condition.²

In the last two years I've fought with several libraries whose documentation makes perfect sense once you already know the tools but is less than helpful when you first meet it. I've slogged through the learning process for Qt (using Q&A sites and blogs mostly³), boost::qvm (frantic trial and error, mostly), and a domain-specific tool whose roots go back to the Reagan administration (more trial and error).

This week I've been investigating logging frameworks. My project could really use one (and I can't use Qt's framework because parts of this code need to run in non-Qt contexts, too). There are a lot out there for c++ and I don't have a good apriori reason to chose anything in particular. I started looking at boost::log first because we are already using boost so it wouldn't represent another dependency. However, this beast has more moving parts than qvm and it's documentation is nearly as bad. I'm abandoning it for now while I look at other things because the documentation is no help at all for what I want to do with it.

So that's the lesson I wanted to get to: if your documentation doesn't help people new to your project they may just walk away. And you have no one to blame but yourself.

---

¹ I developed the term while I was teaching physics. I came to full-time teaching after being a post-doctoral researcher for ten years (and given the length of my stint in grad school that means after being a full-time scientist for about fifteen years). A number of my ex-students still give me grief about the difficulty I had in getting the level right. Especially students from my first couple of years. On the other hand, they've stayed in touch which must mean I did something right around all the frustration and pain I caused them.

² On my current project at work we have finally managed to get the software into the hands of a tester (after about a year of my pushing the issue and for reasons entirely unrelated to my efforts). In addition to the bugs in the software he's identified (about a dozen, none of which were deep or difficult, thankfully) he's made it painfully clear how much our documentation suffered from the insider view. When a Ph.D. holder says your documentation is too dense and assumes too much you know you have a problem.

³ The Qt forums exist, of course, but they suffer from all the faults that Jeff and Joel talked about when they announced their big new idea in 2008. I can't recall and instance where I found a solution therein.