TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Andrew Plato wrote:
> Nobody is asking you to become an expert plug rewirer. But you need to
> know how to do it and you need some first hand experience doing it. Just
> sitting in a meeting and listening to people talk about rewiring plugs
> would not make you a plug rewirer. You need to do it and get some
> experience doing it so you can appreciate what the user is going to go
> through.
> [...]
> What is key is do you understand the content. Do you know WHY you are
> writing certain things and what the greater purpose is behind various
> technology issues. Its when you write in a vacuum, assuming everything
> handed to you from a specification or an SME is correct that you get into
> trouble.
I'm probably, if anything, more technical than Andrew. While I
agree 100% with the second quoted paragraph, I don't know that I agree
with the first.
Hm. Well, on second thought, I think the first paragraph can be
taken two ways, one is that you have to some sense of what the
reader's experience and backgroud is, and that to a degree you can
*only* get this by walking a mile or two in their shoes. I agree with
that.
The other way it could be taken is that you have to master the
topic in order to write about it. This is the extreme view, which I
don't necessarily agree with. Heck, yeah, it'd be preferable to
master the topic you're writing about, always. However, it's not
always feasible, and it's not indispensable. You have to understand
what your SMEs are telling you, and you have to get a sense for how it
works, and yes, you really should be able to sit down and make it work
for yourself.
But to a certain degree, you *do* have to trust your SME, because
there's no way in hell you'll be able to master the topic sufficiently
in any realistic time to finish the docs. So you have to rely on
their guidance, and on their judgement, and on their technical review.
If you're smart, you'll include a wider circle in the review phase,
because a single SME (or multiple SMEs with similar experience bases)
won't always catch everything.
I've worked with writers, whom I otherwise respected, who felt
that their job was merely to extract information from their SMEs,
massage it into intelligible english, put it down on paper, and run it
past the SME and other reviewers to make sure the technical sense of
it wasn't lost. "Just tell me what I need to know." This is, in my
opinion, a minimal job. They have created the form of documentation,
but not the substance.
If you can't get understanding in the process of creating the
document, how can you expect your users to get understanding in the
process of reading it?
The metaphor I use for technical writing is that of a pathfinder,
mapping the route up a mountain. The above approach would be like
hiring a native guide to take you up the mountain, writing down the
directions as you go. Maybe it'll suffice to get somebody to the top
of the mountain, with much work, but is it the best way to get up the
mountain? Is it the way that's best for your readers? Are you sure
the guide understood what you were asking for? Are you sure that the
guide's definition of "top of the mountain" is the same as yours?
In my opinion, you have to survey the mountain, you have to
investigate alternative routes, and you have to talk to your native
guides. You have to build a model of the entire mountain in your
head. Only then can you figure out what angle to draw the map from,
what details to highlight, what to gloss over.
*** 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
TECH*COMM 2001 Conference, July 15-18 in Washington, DC
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.
