Re: Culture, or What it means to be a Technical Writer

[Max Wyss <prodok -at- PRODOK -dot- CH>]

Mark,

as always, it all depends on the product.

There are cases, where you have a high-performance product with lots of
possibilities for the user. One of the important parts of documentation is
that it must be complete. So, you have to describe those possibilities in a
Reference Manual, as it is needed with programming languages. The content
is rather formalized (remember the UNIX man pages?). In such a case you
must not leave anything away. And if it ends up as a 1203 page manual, it
will end up as a 1203 page manual.

Or look at the documentation of a power generation plant. In such cases, a
complete documentation set is shipped on a Euro-palette.

On the other hand, a bloated 1203 page manual may be easier and cheaper to
write than a 160 page highly condensed manual. Some time ago, I had to make
the user manual for a very simple measuring instrument which was very
sophisticated in its way, but had very little interaction with the user. I
ended up with one legal size sheet of paper. On one side, there was a short
introduction, a description of the parts of the instrument, maintenance and
contact information. On the other side, I had an elaborated graphical
representation of the user actions.

And the result ... well, writing a 32 page manual would have been cheaper
for the client.

So, my point is that less can cost much more.


Max Wyss
PRODOK Engineering AG
Technical documentation and translations, Electronic Publishing
CH-8906 Bonstetten, Switzerland

Fax:  +41 1 700 20 37
e-mail:  mailto:prodok -at- prodok -dot- ch    or    100012 -dot- 44 -at- compuserve -dot- com



Bridging the Knowledge Gap



______________


>
>But don't you see, the engineer communicates through the design of the
>product. 1,203 page user manuals result from writers trying to explain what
>engineers have done. If we make common cause with engineers in creating a
>complete product package that is designed to facilitate the users task we
>will describe only what the users needs to know to do the task, and cannot
>discover from the design of the product. Good products are designed for
>discoverability. Good documentation is an extension of that design, serving
>to enhance the inherent discoverability of the product.
>
>It is the writers who forget this, and who simply translate the spec, who
>end up creating 1,203 page manual with useful instructions like "To print,
>click once on the file menu. Move the mouse pointer down to the Print
>command. A dialog box will appear. In the text box labeled "Number of
>copies", type the number of copies you want to print ... " etc. etc. etc.
>
>As co-creators with the engineers we communicate only that which the product
>does not communicate itself. Bad docs are long translations of long
>technical specifications. Good docs are short original compositions that
>complete the usability of the product.
>
>---
>Mark Baker
>Manager, Corporate Communications
>OmniMark Technologies Corporation
>1400 Blair Place
>Gloucester, Ontario
>Canada, K1J 9B8
>Phone: 613-745-4242
>Fax: 613-745-5560
>Email mbaker -at- omnimark -dot- com
>Web: http://www.omnimark.com
>