You are here: Articles --> 1999 --> Using the triage method in technical writing

Vous êtes ici : Essais --> 1999 --> Using the triage method in technical writing

Using the triage method in technical writing

by Geoff Hart

Previously published in a different form as: Hart, G.J. 1999. Using the triage method in technical writing. 4 Lakes Technicalities, Newsletter of the Four Lakes Chapter of the Society for Technical Communication, April 1999:10–11.

[This article was based on an exchange between myself and an anonymous correspondent in the techwr-l discussion group—"Anon." henceforth.]

In a recent discussion on techwr-l, an anonymous poster lamented in part:

Anon.: "... the surgery performed at the MASH hospital is meatball surgery. Get it done and get on with the next thing. Most of the places I have practiced my trade, that's the best description of the technical writing I've been able to do. I cut corners..."

Learning triage skills

I don't thank that experience is the least bit unusual. There's a whole philosophy called "good enough", which recognizes that time and resources are never adequate to do a perfect job. That being the case, I'll extend the MASH metaphor and recommend that you learn "triage" skills. In the technical communication context, triage means that you need to break your information needs into three categories:

1. Information that prevents the product from killing your users or that would prevent your users from succeeding if it were absent. This is the stuff that has to be absolutely correct and presented flawlessly to the extent that this is possible.
2. Information that's not as urgent as that in class 1, and that can wait until you've finished with the class 1 items. It would sure be nice to include this information if there were time, but nobody's going to die if you don't: they're just going to be inconvenienced to a greater or lesser degree.
3. Everything else... the stuff that people will grumble about but "survive" if it's not done.

I'm going to offend a whole generation of editors by saying that many of the little things, like some types of consistency, fall into category 3. For instance, it's pointless to change all "click on the button" to "click the button" if doing so means that you won't have time to write "don't click this button because it will dump the reactor core... a real bad idea".

Clear grammar is a category 1 item, because without it, nobody will understand even the best information. Speaking as an editor now, I fully recognize the importance of consistency, correct spelling, flawless grammar, and so on, but nonetheless stipulate that they're less important than the really substantive issues: you'll look like a slob if you don't get these things right, but at least the documentation will be usable and safe.

Anon.: "Important tasks, such as user analysis, hitting the least-common denominator, site visits, and all the other things that real tech writers do... just aren't possible."

Here's another heretical statement for you: good writing (i.e., concise, clear, and correct) will work for any audience. Sure, it's great to have the luxury of customizing your language to the needs of the audience, but when that's not possible, write well and trust that your audience will rise to the challenge. If you've provided enough information, and expressed it clearly enough, they will... and if they don't, the geek in the cubicle down the row will be able to read it and explain it on your behalf.

Anon.: "Do you perceive that the responsibility to the user and to the profession is so great that the writer has an obligation to do whatever it takes to go after perfection?"

Only if you have a martyr complex. About the only exception I make to that blunt statement is where human life and security are concerned, in which case, it's worthwhile enduring a certain amount of abuse for the greater good. Sure, we all get stressed when Word incorrectly renumbers our autonumbered lists, but we get over it. We might not get over sticking our hand down the back of the monitor to remove a paper clip. Triage again!

Anon.: "Is pragmatism in this situation a copout, or a legitimate survival technique? Is pointing at management merely excuse-making?"

Pragmatism is the necessary first step: do the best job you can do under the conditions. Nobody's going to benefit if you do a superb job on half the manual, then die of stress before you can document the important parts in the second half. However, pragmatism isn't the only step: you need to act as a user advocate to your managers, and make the point as clearly as possible, with as much supporting evidence as possible. The thing that works best for me is to personalize the data for the manager: for example, ask the manager to perform a task that the user interface renders impossible, and you've suddenly got an advocate on your side. If you just mention that it's just difficult, you've already lost your argument. Get a hold of some of the STC publications on quality and usability and use them to provide a financial argument too. These steps can't hurt.

Anon.: "What, if anything, seems to be a magic pill to change it (other than the obvious work hard and pick your battles and try for incremental improvement—which I do)?"

Lawsuits focus attention most wonderfully, but however satisfying it can be to say "I told you so!", they're not the most desirable outcome. Think "glacier" rather than nuclear warfare: it's going to take some time to grind down those mountains, but in the end, you're going to win, and every so often, resistance collapses and you make a real breakthrough. Think "infantryman" rather than knight of the round table: one voice is easy to ignore, but there's strength in numbers. Think differently: sometimes lateral thinking (e.g., getting the customer support manager or an influential client to take up your cause) is far more powerful than a direct assault.

In the end, sometimes you just have to give up and leave, even though that's a copout and can become a self-defeating habit. But if the rest of the job (the people the benefits, the money) is great, see if you can't stick it out in the trenches a while longer.

Sometimes a long, slow, steady push leads to a sudden breakthrough.

©2004–2024 Geoffrey Hart. All rights reserved.