Re: technical Writing Skills

["Doug, Data Librarian at Ext 4225" <engstromdd -at- PHIBRED -dot- COM>]

Sue Gallagher writes:

********************************************
Just because a good tech wirter *can* get around any aspects that
make a product difficult to document doesn't mean "s/h/it" *should*
;-) (you can read that with or without the slashes)

Well organized and well written documentation can point out subtle
flaws in a process. By making that documentation appear to be less
well written or less well organized, we can attempt to hide product
flaws. In the environment in which we work, this *may* be necessary --
but this may not necessarily be the best approach.

[several good examples deleted]
***********************************************


Actually, I've often found that when the explanation becomes *really*
convoluted, it's usually a design problem in the system.  There's some
simplicity lurking out there that the team has managed to miss.

I once tackled the task of explaining a very complex procedure in some
farm financial software.  Many options had to be set correctly to yield
the desired results.  Users constantly messed it up, and the support
and sales people all said "If you can find a way to explain that, you're
really a writer."

After carefully studying the process, it became clear that there where only
two desired results; you either wanted change for the report period or
cumulative change to date.  All the settings boiled down to producing one
of those two results.  I had a chat with the developer, and on the next
release, we added one step to the report, asking if the user wanted change
for the period or change to date, and the system took care of the
settings.

Skoal,

Doug                            "For to win one hundred victories in
ENGSTROMDD -at- phibred -dot- com           one hundred battles is not the acme
                                 of skill. To subdue the enemy without
                                 fighting is the acme of skill."

                                                --Sun Tzu

***********************************************************************
The preceding opinions and positions are mine alone, and are only
coincidentally related to those of Pioneer Hi-Bred International, Inc.
***********************************************************************