RE: You Don't Need to Know How

["Glenn Maxey" <glenn -dot- maxey -at- voyanttech -dot- com>]

Sorry to pipe into this thread so late. I was trying to get some work
done.

Previous postings mentioned that they don't need to know how a VCR or
oven works in order to tell users how to use them. In other words, they
stated that they didn't need to know intimate knowledge of the details
of the device in order to document something meaningful to the user.

I agree that there are lots of tiny technical details that users won't
need to know. However, the tech writer still needs to know them in order
to make the assessment of whether or not these points should be relayed
on to the end-user.

VCR example: when you insert a cassette, the VCR opens the cartridge and
automatically threads the tape through several spindles. A technical
detail. However, it needs to be imparted to the user so that they
understand how it is different from a music cassette tape and why they
shouldn't force a VCR cartridge out of the machine. The VCR tape will be
lodged between spindles, etc. My VCR has three different recording
speeds. How is this achieved? It is important to know so that I
understand the trade-off's of each and so that I don't use the same tape
to record different programs at different speeds (e.g., could make the
tape completely unusable).

Oven example: you do need to understand the technical details of the
oven (i.e., electric, gas, microwave, convection (?)) and need to impart
this technical information to the user when telling them how to cook
with it. Why? It could very well dictate the type of cookware to use,
where to place it in the oven. For example, you don't use metal cookware
in a microwave oven and only imparting the technical details of HOW the
oven works makes clear WHY you shouldn't do that and WHAT you should use
instead. A gas oven heats differently than an electric oven and has
different safety/trouble-shooting concerns relating directly to those
technical details -- even though both cook food.

A tech writing example, RoboHelp/ForeHelp documentation for WinHelp
(which I haven't studied in detail recently and don't even have or use
at my present employer) [as near as I can recall] doesn't go into
details about the difference between their database files and the
generated RTF files. It should. Because then we tech writers would know
that the RTF files (for WinHelp) are more important than their database
files. The main advantage of the database files is that it provides a
type of fake hyperlinking to test out our help systems without compiling
the HLP files.

I believe the same holds true for technical software/hardware
documentation. The tech writer needs to learn all they can about the
product. The value they add is in filtering the important information
from the not-so-important and presenting it in a meaningful fashion.

So I concur with Andrew. You DO need to know HOW.

Glenn Maxey
Voyant Technologies, Inc.
Tel. +1 303.223.5164
Fax. +1 303.223.5275
glenn -dot- maxey -at- voyanttech -dot- com





^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com

---
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.