Why do they need a technical writer?

[Amanda Vogel <pvogel -at- IBM -dot- NET>]

Rose Norman writes:
>I am seeking assistance on how to advise a friend at a small
software company who is having to explain to software engineers
what it is technical writers do that makes them so valuable to
the company.

The following is an extract from a standard blurb I use to try and explain
what a technical writer or technical editor can do for that an engineer can't.
 Perhaps it may be useful to you.  I would also be interested to see what
other techwriters use for promoting themselves.

PROOF POSITIVE

Who writes your technical documentation?  A staff writer? - an engineer? - a
contract writer?

And who reads it? Do you know how well it performs before it reaches the user?

Technical documents which do not meet the needs of their audience most often
fail because they express what is understood by the engineer or technical
writer, not what the user needs to learn. They don't fulfil their role because
they have never been edited or proofread except by an engineer closely
involved with the project.

Every written project needs an independent proofreader, who comes to the
subject matter with an open mind, who is not already familiar with the rhythms
of the text, the labels on the illustrations or the terminology used by the
developing team. Proofreading is a skill.  Not everyone has it and even those
that do often fail to note discrepancies when they have been working for some
time on the project in question.

The proofreader has to check every detail thoroughly:
o       spelling, with particular regard to proper names and
        technical terms
o        grammar
o       consistency of terminology
o       correct use of abbreviations
o       accuracy of cross-references
o       cross referencing of illustrations, headers and footers
        with the body text
o       consistency of style and layout
o       usefulness of the contents list and the index
o       usefulness of headings, subheadings and captions
o       logical sense
o       technical clarity
o       language comprehensible to all users, especially for
        products marketed internationally.

The formidable detail of this checklist is second nature to an experienced
proofreader, who may pick out a handful of errors or inconsistencies in a
couple of pages of brochure copy which have been read by a dozen people in the
process of composition.

A technical editor will further provide a critical analysis of the writing as
communication and make recommendations for improved effectiveness and clarity.
This may include rearranging the material, providing more information or the
same information in a different form, adding illustrations or examples, and
deleting redundant repetition.

A customer who receives a brochure or a new user who opens a manual usually
glances through it for sense. If it works, they may read more. Serious
potential customers will want to read the detail in the brochure. Users  will
typically read part of the manual to check the installation instructions, see
how to get started, try out a few exercises. They'll use the index (if you've
got one) to find out about specific topics, or for troubleshooting. If those
bits of your documentation don't work, they'll stop using it. They'll get on
the phone to you and give you a hard time, or they'll fail to understand the
product.

Inaccuracy looks unprofessional.  The incompetence of poor documentation rubs
off on an otherwise good product, and is an indicator that it has been rushed
to market. Attention to detail, careful layout and good indexing are the keys
to presenting an appearance of professionalism, quality and control.



Cheers,

Amanda