Understanding what you document?

[Geoff Hart <Geoff-h -at- MTL -dot- FERIC -dot- CA>]

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=