Understanding how it works (was: Benchmarking Technical Documenta tion)

Subject: Understanding how it works (was: Benchmarking Technical Documenta tion)
From: "Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 24 Jul 2001 13:09:00 -0400

Seems to me, there are two important reasons to understand how a product
works:

>From _our_ standpoint, many things are hard to document if we don't
understand how they work. Sometimes that understanding makes all the
difference between creating documentation that is accurate and completely
descriptive--but meaningless to the user--and creating documentation that
efficiently helps people to accomplish a task. One of the cool things about
teaching is that you quickly discover whether you really understand a
concept, because you often can't explain something to a student and answer
the inevitable probing questions until you really understand it. That
understanding often lets us identify weirdnesses in a user interface and how
to correct them, for instance. And in a very real sense, we're standing in
the teacher's shoes when we try to teach users (students) how to do
something.

>From the standpoint of our audience, understanding the plumbing often lets
us predict the consequences of that plumbing, thereby sparing the audience
some nasty surprises. Understanding, for example, that diskettes are
magnetic media can help us remember not to store them atop the computer
monitor or expose them to the metal detector wands used at airports; the
electromagnetic fields associated with both devices have been known to erase
material stored on the diskette. (I can attest to both from personal
experience.) That's obviously something the users need to know. Other
examples include databases (the ACID acronym, two-phase commits, etc.),
warnings and cautions, and so on.

So the key, as I see it, is not necessarily to understand everything about a
product, but rather to understand it well enough that we can predict the
consequences of how something works for the user. We can document the
consequences, even if we never breathe a word about the underlying
technology.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html

"Arthur C. Clarke had suggested that any sufficiently advanced technology
would be indistinguishable from magic--referring to a possible encounter
with an alien civilization--but if a science journalist had one
responsibility above all else, it was to keep Clarke's Law from applying to
human technology in human eyes."--Greg Egan, "Distress"

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com

Learn about tools and technologies for user assistance developers at
The Help Technology Conference, August 21-24 in Boston, MA
Details and online registration at http://www.SolutionsEvents.com


---
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
http://www.raycomm.com/techwhirl/ for more resources and info.


Previous by Author: Procedural info.: best way for two systems?
Next by Author: FW: A good grammar test? (Certifying colleagues)
Previous by Thread: RE: [TECHWR-L] formatting suggestion
Next by Thread: Learning Styles (was Benchmarking Technical Documentation)


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


Sponsored Ads