Re: Technical Writing Skills

[Paul Davies <pda -at- IGS -dot- NO>]

John Martin wrote:

"  Clarity of expression is and should be a primary concern."

Depends what you mean by clarity of expression. I have read user
guides in which the individual sentences were paradigms of clarity of
expression (and grammatical correctness to boot!) That did not
prevent the documents  from being next to unusable because they were
badly organised, contained information that was irrelevant, and lacked
information that was vital.

It is a common fallacy that technical writers exist _primarily_ to write
nice prose and get the grammar right. I do not deny that that is a
part of the writer's brief. But far more important is the selection
and organisation of information to satisfy the needs of the identified
readership. How much are 100 words of well-turned out prose worth when
the information could have been conveyed much more effectively in an
illustration or a matrix?

He continued in the following vein:

"  Gosh, gee!  Two, maybe three weeks to master UNIX and data packet switching?
   Perhaps, then, a month to absorb all the newest developments in
   telecommunications?  Usability theory and practice should only take
   us hours to absorb?

"  Forgive my sarcasm.  I have seen so many people try to enter this
   field, not just lacking technological expertise, but with the
   (often sullen) expectation that the writing and editing skills
   they've garnered have *earned* them something above and beyond what
   ordinary mortals have earned.  That attitude simply isn't true.
   Worse, that mindset is detrimental not only to the individual but
   to our fledgling field as a whole."

Sarcasm is excusable only when it is used in the service of wit.
Perhaps the sullenness that Mr Martin describes is the frustration
that many technical writers experience when confronted by yet another
recruiter who is much more concerned with specific technical knowledge
than the ability to produce user guides that are genuinely useable.
This frustration is not borne of writers' resentment at being denied
access to jobs they don't deserve. Rather, it stems from the realisation
that the undervaluing of our writing and editing skills by many
shortsighted recruiters is directly responsible for all those bad
documents out there that are bringing our profession into disrepute.

What also frustrates many writers is the struggle to gain acceptance
of the idea that the design and implementation of quality
documentation require skills as valuable and as specialised as those
required, for example, for the design and implementation of computer
software.  When it comes to the production of quality documentation,
these skills are more valuable than specific technical knowledge. I am
not, however,  arguing that writers should write from a position of
ignorance. One of the most important skills a good technical writer
has is the ability to research a new subject and quickly gain an
understanding of it. This will entail making effective use of
technical information provided by technical experts. It is not usually
necessary to absorb _all_ the newest developments in
telecommunications to write effective user documentation, even for
telecommunications products.

User documentation usually benefits from the writer _starting_
from a position of ignorance and asking exactly the questions that the
readers will ask. Starting with too much detailed knowledge may
actually hinder the process. And what price knowledge over
understanding when you start work on a totally new development?

Just my tuppence worth.

--
Paul Davies

Information & Graphics Systems AS
Postboks 470, N-1371 Asker, Norway

Standard disclaimers apply.