Re: Understanding the things you document

[Dan Lewis <danlew -at- DELPHI -dot- COM>]

Thom Randolph wrote:

>It probably depends on the product complexity and the amount
>of that complexity "surfaced" to the user.

I think there is another point which is perhaps an amplification of this.
I write manuals for users of a software product.  What I am documenting,
almost exclusively, is the user interface.  While on occasion I do need to
at least describe some of the algorithms, or their underlying assumptions,
most of my documentation is task oriented and descriptive.  For this sort
of documentation I would argue that it is something of a benefit NOT to
know too much of the detail.  I purposely avoid paying a lot of attention
to the engineers before I get my hands on the interface.  This way I can
more easily put my self in the mind set of the user.  My expertise lies
more in my ability to scope out an interface and break down complex tasks
into simple steps.  Often in the process of doing this I discover bugs in
the interface that those who already have a firm knowledge of what is
supposed to happen don't notice.

-Dan Lewis
Vitel Software, Inc.
Worcester, MA


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