Understanding what you document?

Subject: Understanding what you document?
From: Geoff Hart <Geoff-h -at- MTL -dot- FERIC -dot- CA>
Date: Wed, 7 Jul 1999 08:41:28 -0400

Jonathan Soukup observed that <<With everything I've documented
in the past, I have always understood at some level how the device
or program worked. I'm getting the picture at my new job that
understanding the program is secondary to producing the
documentation. Do other writers face this same challenge?>>

Understanding your subject may well be secondary, but that
never means that it's unimportant. After all, you can certainly
document things that you don't understand, just as you can
operate things that you don't understand (e.g., driving a car
vs. repairing it). But ask yourself this: Do you (or the reader
of your documentation) have more of a feeling of control and
confidence if you understand the product, or if you're just
following meaningless instructions? Rote instructions are for
robots and the internal logic of computer programs; for
humans, aim to provide comprehension.

--Geoff Hart @8^{)} Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca

"Though the editor is the author's ally, she should never forget that
she is also the reader's first line of defense."--Shoshanna Green


From ??? -at- ??? Sun Jan 00 00:00:00 0000=



Previous by Author: Rules for quotations: techwr-l tie-in
Next by Author: Cataloging graphics?
Previous by Thread: Many Thanks!
Next by Thread: Re: Understanding what you document?


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


Sponsored Ads