Re: Lowest Common Denominator/Reading to Learn

[Steven Jong <SteveFJong -at- AOL -dot- COM>]

Knowing your audience, and its skill set, is key. So is understanding the
nature of your product and the way it's used.

I cut my teeth documenting software applications ranging from somewhat complex
(office automation) to mind-crushingly complex (networking). These products
were expected to be used infrequently to regularly. This established certain
biases in my mind, which sometimes clashes with the reality where I work now.
My company has a mix of products: some indeed fit my world view of software,
but some are essentially simple data-entry applications for dedicated users
(that is, their entire job is to sit in front of a screen running one of our
applications exclusively). Documenting the latter products forces us to think
differently.

For dedicated users of a simple application, they learn what to do quickly,
and then never forget it. (At least, this is what our trainers tell us.) There
is no time to look up anything in a reference document or even a user's guide;
instead, we seem to have success with quick-reference cards, suitable for
showing new hires how to handle the major tasks. There are some "nooks and
crannies" where uncommon or obscure tasks need to be done, but not many.

We customize our software for various clients. Some have asked for thorough
reference documentation of fields (field name, data type, field length,
default, etc.), which is what I was used to doing; but because the
applications are sometimes quite simple, this results in a culture clash.
(When I bring up the subject of reference documentation for all fields, the
response is always, "Why? What's to document for the 'First Name' field?")
There are some non-trivial fields; for example, for a business customer, our
users sometimes have to enter three trades. To this day I'm not positive I
know what a "trade" is! But we're told that our users are completely familiar
with the term, and it's insulting to tell them. Hmm... A final problem is that
some fields simply collect data that we pass on to client systems for
processing; thus, even we don't know what the fields mean! How can we document
them?

          -- Steve

Steven Jong, Documentation Team Manager ("Typo?  What tpyo?")
Lightbridge, Inc, 67 S. Bedford St., Burlington, MA 01803 USA
mailto:SJong -at- lightbridge -dot- com 781.359.4902[V], 781.359.4500[F]
Home Sweet Homepage: http://members.aol.com/SteveFJong

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