Re: technical Writing Skills

Subject: Re: technical Writing Skills
From: "Doug, Data Librarian at Ext 4225" <engstromdd -at- PHIBRED -dot- COM>
Date: Mon, 13 Feb 1995 15:25:32 -0600

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


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.

Previous by Author: Re: Process Modeling--Tool Selection
Next by Author: Re: Writing Platform
Previous by Thread: Re: technical Writing Skills
Next by Thread: Re: technical Writing Skills

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

Sponsored Ads

Sponsored Ads