The Bits and Pieces IX: Documentation in Practice

So let’s say the stars align and your child’s unicorn is delivered on time, and you actually do have a dedicated documentation writer and training developer on your project. What kind of documentation works best?

I suppose everybody prefers something slightly different. (I personally would love to see the “kinesthetic” documentation for an XML workflow. “Aural” would be cool too.) Most of the time, though, documentation is going to be a fat binder with page after page of text and screenshots, or something online with similar text and pictures linked together in some fancy way.

I feel that you need to have several kinds of documentation available to users. For our content model, we created a very detailed catalogue of all the XML elements and attributes, with tree models to show how the parent/child relationships worked, and output screenshots to show what the XML tagged content would look like “on the page”. I thought it was very thorough yet concise at a mere 300 pages. The users thought it looked like “stereo instructions” and didn’t find it helpful at all. I guess the fact that I helped develop the content model, so I pretty much knew it backward and forward to begin with, clouded my judgment of the catalogue’s usefulness.

So based on that epic fail, we created a booklet of “quick topics” that featured lists of steps in various procedures. Need to know how to import an art file? Here’s the step-by-step instructions. Some of them even had screenshots to show what menus to choose or buttons to click. These were slightly more useful than the catalogue, but most of them had 20 steps or more—the steps add up when you make “click on the OK button” its own step. And there are 12 instances of that in a particular process. (Maybe our processes were too complex? A topic for another time perhaps.)

We also had a design catalogue of the various styles available. This actually was helpful as authors and editors developed the concept for certain kinds of pages. When there are 14 different styles available for questions, it’s nice to have a picture of what they all look like. But even this was limited. They had to look in the catalogue to match the design to the XML that was behind it. And they already didn’t like the catalogue because it was too confusing.

I think our main failure was to organize the documentation and training around how the system worked, not how the users would work. A chart of elements and attributes is pretty useless when you don’t know what any of the elements and attributes are for in the first place. Describing steps in using software in terms of the software rather than in terms of your user’s workflow and tasks is also less than helpful. I’m not “uploading a binary object into the docbase”, I’m “putting the picture of George Washington into the system so I can put it on this page.” I’m not “editing formatting attributes for composition”, I’m “making this paragraph be in 2 columns so it fits right.”

For our new attempt at an XML workflow, I hope we can develop documentation that’s short, uses language familiar to users, and is well indexed so it’s easy to find everything. Ideally it would be available online in a help menu within the interface itself. I wouldn’t go so far as to want that stupid talking paperclip thing that interrupts you when you’re typing, but some contextual help would be very cool. We should still have exhaustive catalogues of our elements and attributes, but those would be for the technical people working behind the scenes.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: