Re: Understanding the things you document

Subject: Re: Understanding the things you document
From: "Jessica N. Lange" <jlange -at- OEE -dot- COM>
Date: Wed, 7 Jul 1999 07:52:31 -0400

You (the writer) start out knowing nothing--just like the user--
so you ask the same questions and make the same mistakes
that the user will.

At the end (when the documentation is complete), you should
be an expert. This comes through SME interviews and using
the product in the same manner the user would.

The SME has a different outlook on the product than the user.
He/she explains things to the writer at a different level than
the user needs. If the writer is a SME, the user's needs may
be forgotten. Once you know how to do something, it's hard
to remember what it was like when you *didn't* know it: how
frustrating that could be, how you didn't even know the
right questions to ask.

I recall one aspect of our product that I had to document.
It was hard for me to understand. I asked all the SME's I could
find (different perspectives, different ways to explain). All of
them responded to my questions by drawing charts & curves
& telling me about algorithms. I kept asking "But why would
the user want to use this? What is the result he's seeking that
this feature will produce?"
It was a trainer --who used the feature-- who finally explained
it to me from the user's point of view. If I had been an
engineer, my documentation wouldn't have been of much use
to a user (who aren't engineers). Because I didn't understand,
I continued to ask questions---as a user would---until I did.
That helped the documentation.

If we--tech writers--are the "user advocate," how can we be
if we are also the SME?

Jessica N. Lange mailto:jlange -at- oee -dot- com
Technical Communicator, Ohio Electronic Engravers, Inc.

From ??? -at- ??? Sun Jan 00 00:00:00 0000=

Previous by Author: Re: FW: HTML Help: Use of secondary windows & usability
Next by Author: FW: indexing
Previous by Thread: Re: Understanding the things you document
Next by Thread: Re: Understanding the things you document

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

Sponsored Ads