Re: STC Letter to the Editor

Subject: Re: STC Letter to the Editor
From: cpwinter -at- rahul -dot- net
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 4 Nov 2002 19:09:37 -0800


On 4 Nov 2002, at 7:02, SteveFJong -at- aol -dot- com wrote (in part):

>
>
> Do you have any suggestions how to assess the technical accuracy of a
> document without access to the product it documents? Does anyone?
>
Steve,

You are correct that it is impossible to fully evaluate the technical
accuracy of a document (an instruction manual, for example) without
having either

a) access to the equipment it describes, and sufficient time to work
through the manual, or

b) technical knowledge of the equipment (perhaps as one of the
designers of said equipment).

However, absent these, it still ought to be possible to form an opinion
about the document's accuracy. There are three sorts of clues: poor
grammar or spelling, mis-statement of basic knowledge, and lack of
internal consistency.

If I see a document that contains many spelling errors, especially if
certain words are consistently misspelled, or if it exhibits poor grammar,
I tend to expect that its accuracy is similarly below par. This might not
be true, but it would be my subjective impression. I buttress this by
noting that correct spelling and good grammar are easier to achieve than
accurate content, especially with the tools that writers have today.

A document that makes errors about basic physical facts is obviously
suspect. Saying that, when "jumpering" the drained battery in a car, you
should connect the positive terminal of the good battery to the negative
terminal of the drained one, would IMO be such an error. (True, there is
room for debate about whether everyone would spot this particular
mistake. But there are, certainly, basic facts that everyone can be
expected to know.)

As for lack of internal consistency, this will be apparent in most any
set of procedures. Examples might be changing the number of a switch
(but not its name) from procedure to procedure, or transposing the order
of two adjacent steps in a procedure, if the same procedure appears
more than once in the document. I'm sure anyone can imagine many
more such examples.

I think, therefore, that to say any judging of the quality of technical
documents other than that done by the customer -- the operator or user of
the product the document describes -- can only evaluate quality of
presentation is to miss how readily apparent many sorts of technical
errors will be, even to someone totally unfamiliar with the product or
technology described.

Chris




^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Check out SnagIt - The Screen Capture Standard!
Download a free 30-day trial from http://www.techsmith.com/rdr/txt/twr
Find out what all the other tech writers, including Dan, already know!

All-new RoboHelp X3 is now shipping! Get single sourcing, print-quality
documentation, conditional text and much more, in the most monumental
release ever. Save $100! Order online at http://www.ehelp.com/techwr-l

---
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit
http://www.raycomm.com/techwhirl/ for more resources and info.



Follow-Ups:

References:
Re: STC Letter to the Editor: From: SteveFJong

Previous by Author: RE: Warnings
Next by Author: Summary list of recent "What do you document?" thread
Previous by Thread: Re: STC Letter to the Editor
Next by Thread: Re: STC Letter to the Editor


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


Sponsored Ads