Re: Documentation seminar

Subject: Re: Documentation seminar
From: Michael Lewis <lewism -at- BRANDLE -dot- COM -dot- AU>
Date: Wed, 4 Mar 1998 22:35:34 +1100

Warren, I think you're missing the most important point, which is -- as
you imply yourself -- that the technical people (call them engineers,
programmers, or whatever) simply do not appreciate the role of
documentation in the overall scheme of things.

It shouldn't be true, but it is, that a lot of technical people think of
documentation as "something the customer expects, so we have to provide
it". They think their creation is perfect, or at least perfectly
useable, so documentation is to them an expensive way of pandering to
irrelevant mind-sets.

The best line for your seminars, IMNSHO, is to push the "support effort"
line. Documentation is part of the user interface: the users refer to it
as part of the learning process. The less effective that documentation
is, the more problems there are in product support and even warranty
claims. (Notice how the makers of domestic appliances try to protect
themselves by including statements like "Failure to follow these
instructions will void your warranty" in their user docs.)

In short, people need to see the documentation as part of the product.
If the documentation is produced too quickly, with too many corners cut,
compensating costs will show up elsewhere.

At the same time, of course, costs of documentation production accrue to
different parts of the organisation than the costs of documentation
failure. (See the article by Ginny Redish in the STC's Technical
Communication of 1st Quarter 1995 for some really powerful thinking on
this head.) That means you need to get the next line of management
involved -- they need to see the total cost picture: not just the costs
of getting the docs right, but also the costs of getting them wrong.

Warren Singer wrote:

> ... I decided it would be of benifit both to me and the company
> to "educate" R&D and program managers by providing a forum for discussing
> documentation issues.

Michael Lewis
Brandle Pty Limited, Sydney, Australia
PO Box 1249, Strawberry Hills, NSW 2012
Suite 8, The Watertower, 1 Marian St, Redfern 2016
Tel +61-2-9310-2224 ... Fax +61-2-9310-5056

Previous by Author: Re: Incorporating Pagemaker in a Tech Writing Class?
Next by Author: Australian Conference '97: proceedings available on CD
Previous by Thread: Documentation seminar
Next by Thread: Documentation seminar -Reply

What this post helpful? Share it with friends and colleagues:

Sponsored Ads

Sponsored Ads