Technical Writing: a Calling?!?

[Moshe Koenig <alsacien -at- NETVISION -dot- NET -dot- IL>]

I have read the discussion regarding remaining faithful to the English
language and to the user. That's a bit of an oxymoron, but the truth
is that good English doesn't have to be florid, purple prose, either.
In fact, I would go so far as to say that technical writing is writing
that is transparent by definition; the writer becomes invisible in
good technical documentation. When the write becomes visible is when
the documentation is NOT good; when the language is garbled, unclear,
lacking in focus, not to mention grammatically and syntaxically flawed.

Plenty of people can argue, "How much talent does it take to write:
'Step 1 - do this; Step 2 - do that'?" The answer: it takes PLENTY of
talent. An accomplished writer has to use a considerable amount of
discipline to write clear language in short, terse sentences without
a lot of ponderous, esoteric terms. No matter how technically complex
the subject matter becomes, the language for explaining it still
remains simple and functional, designed for getting the information
across, not for winning the Nobel Prize for Literature. A technical
writer has to be creative to find ways to present information without
turning it into a cure for insomnia and yet still to stay functional
and to emphasize the useability of the documentation above all else.
That's no mean feat!

I forget who said, in her brilliant book, "Few people have lives so
devoid of meaning that they read technical documentation for their
enjoyment." It's true! We'll never make the Best Seller List, nor will
anyone make a miniseries from what we write (that WOULD be a sure cure
for insomnia). Good technical writing is demanding.

Where does the issue of violating the language come into question? Once
on a job, I was writing an online Help topic, and there was one sentence
that, no matter how I tried to reword it, seemed to read more naturally
with a (thunderclap) split infinitive. Using a split infinitive was
against everything I believe and advocate, and I was very uncomfortable
about it. However, when I rewrote it without splitting the infinitive,
the language sounded so stilted and pedantic that it grated on the
nerves. In this case, I deferred to the department head, who authorized
the split infinitive. Grammarians do permit split infinitives on
occasion, but there are still many people who go ballistic at the
sight of a split infinitive, just as there are still musical purists
who retch when they hear parallel octaves that recalls music before
the 20th century. With time, who knows? I remember being told that a
contraction was punishable by death, so anything is possible in time.

I think the key remains "useability". A user can certainly use clearly
worded documentation much more than badly worded documentation. Things
like prepositions at the end of a sentence may not faze the user as
much as the writer. However, no user wants to see something sloppily
written, because eventually the slouchy writing will become unclear.

Use of jargon and slang are separate issues. Jargon restricts the target
audience to a specific sector that is familiar with the terms in use;
slang restricts the target audience to a specific period in time and
perhaps also geographical location. The rule of avoiding both is not
arbitrary; it is designed to make the documentation useable to the
largest audience with the fewest rewrites.

What I find more annoying is the practice in many companies of using the
technical writer for all sorts of odd jobs by virtue of the writer's
command of English and of software editing tools. Companies that do
this sort of thing turn the technical writer into a Jack-of-all-trades
who finds not enough time to write documentation or finds just enough
time to do a second-rate job. This topic, to my way of thinking, merits
discussion in depth, because I know how annoyed I used to get when I
would be called to sit in meetings in which the people argued for hours
over issues that were certainly of no interest to me and were not in
any way issues to raise in front of a customer. Here I did not have to
be concerned about preserving the purity of the English language nor
about representing the user's interests; I didn't stay awake that long.

Am I being too caustic? I don't think so. I feel that technical
communications as a profession is still not well understood, even by
persons who are often supervisors to technical communicators. Currently
in Israel, technical writers have been debating the possibility of
developing a full-fledged certification program for technical writers
on the university level; the discussions indicate that many of the
writers themselves are very ingrown into the demands at their places
of work and do not appreciate fully enough the latitude that exists
in the field. In my opinion, there is still a lot that needs to be
done to define the role of the technical writer more clearly.

- Moshe

                  TECHWR-L List Information
To send a message about technical communication to 2500+ list readers,
E-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send administrative commands
         ALL other questions or problems concerning the list
       should go to the listowner, Eric Ray, at ejray -at- ionet -dot- net -dot-