Documentation

I was thinking about documentation a little while ago. I was not happy.

Here's the deal. I support a product for one of our customers. My support is limited to getting new releases of it and installing it. On occasion, when they have a problem using it, I'll call the vendor, get an answer, translate if needed from geekspeek to realtalk, and pass it on. A few weeks ago, I was asked to join a group that's doing a customer conversion from a competing product to this one. It took quite some time to get an id on this customer's system (I get to do three different signons to get in; everything but jumping up, twirling my chair, and sitting down again), and so it wasn't until this week that I actually saw what they wanted us to do. At first I was stunned: I had no idea how this other product worked, so converting it seemed to be impossible. But I spent several hours reading their online documentation, and after a while I began to get the idea, at least for the two reports that I was working on. The concept turned out to be pretty simple, and I thought there would not be much difficulty in creating a clone for these reports in the new product.

Ho, ho, ho.

I just spent about three hours trying to figure out how to do something relatively simple (I don't want to say exactly what it is, but its roughly of the level of complexity of this: "For the biggest room in your house, count the number of places that someone could sit, and for each one, list whether its a chair, couch, or something else, and tell what color it is.") I could write code to do this function in less time than that. (Well, actually, probably not. The actual productive time would be less than that, but I would spend more time flailing around and cursing my stupidity in coruscating terms.) I pored through the documentation for the new product, but I couldn’t find a thing that told me what I wanted to know. The problem? The format.

The doc is a PDF, which is good if you just want to read but not so good if you're not exactly sure where to find what you're looking for, or what format it might take. To use the example from before, am I looking for 'room' or 'living room'? Am I looking for 'seat', or 'seating'? Is seat a verb or a noun? If this were paper, I could flip through it and eventually -- probably -- find what I want. Or at least find what looks like which I want. But when I'm using the PDF search function, which is not all that powerful, I'm limited to guessing, a lot. To make life more fun, the search function apparently doesn't care about the formatting of words. If I'm looking for the phrase 'seat cushion', it thinks that "This is the seat cushion." and "This is the seat. Cushion it well." are both valid items to return from its search. As problems go, this isn’t a really big deal, but it is irritating. Its not the way things ought to work.

Am I the first person to come up with this question? Probably not. So why can't I go find out if anyone else has asked this question before, and what answer they got? And why doesn't the documentation reflect that answer? Well, a big part of that is because this documentation is static. Someone wrote it, someone else formatted it, and someone else put it into a PDF document. If thirteen microseconds after the PDF was made they found an egregious error somewhere in the doc, they can't change it without going through the process again. Which raises the question: why is it static? Why doesn't this company (which is kind-of a computer company, though not as much of one as mine, the Biggest Little Software House in the World) use dynamic documents, all HTMLed to within an inch of its life? Why can’t the customers update the documation, showing how the product is actually viewed in the real world - ie, the wiki idea?

I am willing to believe that there are people who spend their lives trying to devise useful, flexible documentation that speaks to both the power user and the neophyte, that answers the question that everyone asks and the question that only the geek asks, that satisfies the desire for the Big Picture and for the Nitty Gritty. Documentation that’s elegant and responsive is hard to come by, and people don’t buy software for the documentation. But the increase in functionality of products doesn’t count for much if you don’t know that it’s there.

A little Strunk and White, anyone?