RE: Concepts (was Technical Writing Tests)

Subject: RE: Concepts (was Technical Writing Tests)
From: "Jennifer Rondeau" <jrondeau -at- fabtrol -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 18 Feb 2003 11:01:08 -0700

I've been reading this thread and its relatives for the past week, and I'm
finally compelled to contribute (as it peters out . . .).

Gene provides a great summary of the market for procedures-based
documentation (and, I would add, training). Andrew has given a compelling
but largely theoretical argument against being satisfied with this
approach. But there are practical reasons for its ultimate inadequacy and
(I would argue) failure, too.

Whether workforces are dumbed down and workloads increased or not (and
it's certainly my perception that they have been), if workers don't
understand the larger picture of what they're working with in (for
instance) a complex CRM or ERP system, the system will (at least
eventually) routinely fail everyone who tries to use it. If you don't
learn how what you do with such a system affects everyone else who uses it
for different tasks from yours (the conceptual level), you'll never carry
out your own tasks with the degree of care and understanding necessary to
make the whole system work consistently (I'm not even talking about
working well). And the same thing is, of course, true of other complex
systems as well, including but not limited to computer software.

In the case of the system at my present place of employment, the
documentation itself isn't at fault -- it is so exhaustively complex that
only our IT manager is deemed to have the competence to deal with it. The
rest of us, however, are expected to muddle along with bits and pieces of
instruction and training that do not explain anything about how the system
itself works. Data gets lost or corrupted all the time, and then we whine
about what a lousy system it is. It may not be the world's greatest, but
our implementation and training leave a great deal to be desired,
precisely because we focus on procedures and not on concepts (to use the
vocabulary of the current discussion).

Now, I'm not suggested that my entire company should be invited to spend a
week pondering the flow chart for our CRM system, which occupies one
entire large wall in exceedingly fine print (although John Posada might
want to . . . :>)). But some basic overall explanation of how the system
works does not require such detail. If you assume that nobody can
understand the concepts at all, guess what?

Jennifer Rondeau
Marketing and Documentation
(yes, both)
FabTrol Systems
Eugene, Oregon
jrondeau -at- fabtrol -dot- com

GeneK wrote:

It's my experience polling users that over the past 5 years or so "forced
users" are rapidly becoming the majority, as employers "dumb down" their
workforces by laying off skilled professionals and replacing them with
cheaper hourly labor. And even those users who might have the interest to
read the conceptual info are increasingly under workloads that don't
permit them the time (for example, having to supervise all that cheaper
labor). This doesn't necessarily mean that the more conceptual info isn't
called for, but it has resulted in my reordering most of the documentation
I've produced in recent years to provide "___ for dummies" style
instructions in small volumes or on plastic-coated cards that won't panic
users who have 15 minutes to operate an instrument and then have to move
on to the other 50 tasks they have to complete before lunch, and moving
the deeper material to separate reference volumes - and increasingly,
online files to reduce printing costs - for info that the Marketing or R&D
people decree that "hardly anyone reads."

Gene Kim-Eng
Technical Publications Manager
Half Moon Bay

At 06:54 PM 2/14/2003 -0800, Andrew Plato wrote:
>The people who actually read docs (in order) are:
>1. Your boss
>2. Your co-workers
>3. Your competitors
>4. Potential customers
>5. Other tech writers looking to rip off your styles
>6. Forced users
>7. The curious
>8. The honestly diligent reader


Buy or upgrade to RoboHelp X3 today and receive the WebHelp
Merge Module for FREE ($299 value). RoboHelp X3's all-new
features include conditional text, completely re-engineered
printed documentation output, Context-sensitive Help Toolkit,
single-source layouts, and more!
Order online today at

You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit for more resources and info.

Previous by Author: Re: Meta-Topic On Discussions (delete as appropriate)
Next by Author: RE: To upgrade or not?
Previous by Thread: RE: Concepts (was Technical Writing Tests)
Next by Thread: RE: Concepts (was Technical Writing Tests)

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

Sponsored Ads