Usability vs. Maintainability in Technical Documentation
November 13th, 2008Last night, I attended our monthly STC Intermountain Chapter meeting. Bob Lindsay, an e-learning developer and manager, presented some tips on writing for e-learning modules.
Some of his tips regarded how to reduce necessary maintenance on your modules. The bottom line in this part of the presentation was to keep things generic when possible so that, later, there is less to have to change when the product changes.
Bob invited questions and discussion, and my manager, Kurt, made a comment about being a detail-oriented writer. He thought that avoiding specifics goes against his objectives. I have to agree on that. Bob’s tips were mostly small things you can do that will save you time later and would probably not impact your deliverables in a dramatic way; but in a larger sense, ease of use butts heads with ease of maintenance.
Let me give an example.
Generic: “To turn on the machine, press the Power button.”
Specific: “To turn on the machine, press the Power button, which is located on the top of the device.” (…plus an image of the button, plus an image pointing out where on the machine it appears.)
Which one is easier to maintain? Which one is more helpful?
I’ll ask a different way. Which one is better for the writer, and which one is better for the audience?
The optimal situation for me would be a one-time writing process at the end of which I could walk away. No maintenance, no updates, and no revisions. That would be an easy project. All the detail you want with no regrets.
However, most projects don’t fit that description. Competitive markets call either (1) for the next version of a product to be better than the other brand, to do things faster and easier; or (2) for product development to use the latest technologies that have come about because of #1. Or both. There’s nearly always a next version, the one with more muscle, higher speed, and shinier chrome.
While that means a job for the technical communicator, I don’t want to spend all my time updating images and tweaking text. I want to be developing new content. Rewriting isn’t as fun as writing.
Change is inevitable. Given that we can expect to spend time maintaining content, how can we make our own lives (or the lives of those who follow) easier? How can we reduce maintenance time and effort (which means cost) while still giving users specific information that satisfies their needs?
I don’t have a bunch of answers right now. I just started thinking about this last night, after all. I’m hoping to give some thought and practice to striking a balance and to then post the results. So I’ll be letting you know what comes out of the oven.
Subscribe to the Journals 
November 24th, 2008 at 10:48 am
I’ve been thinking about this, too, because I’m working on a project that was recently imported into Flare to be single-sourced. On top of that, the product is now in rapid development instead of waterfall development. So the whole project has leaped into the 21st century. Warts and all; inconsistent headings and organization, incompletely documented features, etc. So, another writer and I are trying to clean those things up while adding a long list of changes on an aggressive schedule. Prioritizing is a must. I have been reassuring myself with every change I document, “You got the main flow of the change. You tried to find every procedure and window that may be touched by this change,” (I’m new to the product, too), “but it’s possible you missed a minor one. Users will be able to find the topics you wrote and get the information they need. Time is up for this change.”
In the example of the button that you gave, if the button moves or changes, you’ve got rewrites in every procedure it is listed in. If you have it in a snippet or variable, you have to rewrite each snippet or variable for each button that moved. If you’re in my shoes, you have to find every place the step occurs and turn it into a snippet or variable. It may be that time could be better spent documenting a change that is more likely to stump people. If there is no procedure on how to web-schedule a patient, for example, maybe more people will have trouble than if you omit a detailed description of where to find the Power button.
That said, I do like to have an image of a button; especially if the button contains no text.