Here’s something I’ve been working on as a support for training my documentation team to convert to XML, which is a bit more fun than it sounds like but requires some fairly fundamental rethinking of what a writer does. There is a labored and over-extended analogy with bees, but I think I might keep that in.
————————
To supply user documentation for a diverse, overlapping set of products, you have to maintain your information in tight, clearly delineated modules that you can mix and match wherever they are needed. To do this, you must discard the old book-based model that has defined most online documentation until recently, and make the transition to an agile database model.
What’s wrong with the old way?
Online documentation started out as an effort to duplicate the experience of reading a book, which was the main way people were used to getting information before computers became widespread. You can see the influence of many generations of book-reading in the language we use to talk about online experience: pages, scrolling, sections and headings, libraries, and so on. The book model was successful because its structure supported the way people actually interacted with things and events in the “real world,” as they called it (or “offline,” as they didn’t call it).
The problem is, online experience is very different from “real life.” Events are much more fragmented: you do one thing here, jump somewhere else to read something, come back for a moment, reboot, pull in some snippet of data from over there. Online experience doesn’t feel like the rhythmic, sequential narrative structure that we value in the books and manuals that we read on paper.
The supplies of information that we rely on to help us get through this madness don’t help us very much if they insist on portraying a world in which one thing follows another and everything develops according to an authoritative, reliable timeline. We need information to be available for just the activity we are on, at just the time we need it, in just the amount and at just the level that makes sense right then.
That’s the consuming side. As suppliers of information for people using computers, we’re called on to provide information that supports the way our readers actually behave online. If our information is locked up in large, unique, cohesive batches of prose, we can expect to spend most of our time searching and editing and managing those batches, leading to more and more duplication, inefficiency and human error.
What’s good about the new way?
Real computer users can be compared to a bee in a garden. They hover around, briefly select a landing place and move on when they have what they came for, then do it again. Their effectiveness is determined by how much they can get out of each flower they visit. The more specific information they can derice from each of those flowers (What is this color exactly? How did I get here? How much pollen can I get from this variety?), the better their overall honey-making day.
We can’t predict which flower a bee will visit next. We can predict, though, that it won’t follow a schedule of stops at particular ones. That’s what a manual is, or a guide: a schedule of stops at particular screens, pages or resources. We would never offer a bee a schedule for its pollen-gathering chores: that would be silly.
What we might do instead is develop a collection of discrete bits of information about all the different things the bee has to get done. Some of those bits only make sense when a bee is visiting a particular species of flower. Others are more generally useful, like navigational hints.
It would take some work. We would have to watch the bees carefully, to develop a model of where they go and how they do things. We would have to keep close track of our bits of information, so as not to describe the same thing twice, or leave out something important.
Then, if we could figure out a way to attach to each flower a unique set of those information bits, including everything the bee needs to know right then and there and nothing it doesn’t need to know, we could really make that bee a champion pollen-collector.
If our information bits were sufficiently standardized so we could mix and match them freely, we could put together such a set of information on the spur of the moment, even for a flower that we didn’t even know about.
If, on top of that, we could make that information pop up in front of the bee, with the bee barely even realizing it had triggered it, we would be revolutionizing the work lives of bees. We’d be on the cover of National Geographic.
