Meatball technical writing? Try triage!

["Geoff Hart (by way of \"Eric J. Ray\" <ejray -at- raycomm -dot- com>)" <ght -at- MTL -dot- FERIC -dot- CA>]

The long-suffering Anonymous described <<...the surgery performed at
the MASH hospital as 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>>

That's not in 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 techwhirling 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
gonna 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, but at least the
documentation will be usable and safe.

<<As far as things like user analysis, hitting the least common
denominator, site visits, and all the other things that real tech
writers do, they 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.

<<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 is 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!

<<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
got an advocate on your side. If you just mention that it's
difficult, you've already lost your argument. Get ahold of some of
the STC publications on quality and usability and use them to provide
a financial argument too. Can't hurt.

<<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 different: 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 money, the benefits) 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.

Best of luck, whatever you decide.

--Geoff Hart @8^{)}     Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca

"Patience comes to those who wait."--Anon.

 From ??? -at- ??? Sun Jan 00 00:00:00 0000=