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.
Subject:RE: Are these words being used? From:"Susan W. Gallagher" <sgallagher -at- expersoft -dot- com> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Tue, 09 Nov 1999 16:38:12 -0800
>Tony Markatos said:
>
>... it is
>impossible to "clearly translate what the SME says" without an in-depth
>understanding of the of the product.
>
>Jim Shaeffer observes:
>
>A common scenario...
>1. ... (SME) gives ...(TW) a document
>2. The TW ...transliterate ...into correct>English.
>3. ...document is returned to ...check ...technical accuracy.
>If I can rearrange the words and phrases used by the SME to improve their
>flow and grammar (and throw in an occasional synonym), I can do the job
>without understanding the technology being discussed.
Now I'll add my two cents:
It is certainly easier to create usable documents about a technology you
understand, but just because you don't understand the subject matter doesn't
mean you've lost all abilities to determine what's good information and what's
bad (useless). It certainly doesn't mean you've lost your ability to ask
questions. And so, I maintain that you can have a profound influence over a
document -- not just wordsmith it, but influence its structure and content --
without ever understanding the technology it talks about. I know, I've done
it.
I work in "bleeding-edge" software. Sometimes it takes me a while to catch
on. But that doesn't stop me from barging in and laying claim to the
documentation.
I know that the most common complaint about documents written by
programmers is
that they tell you _everything_ about the software except how to use it. After
wordsmithing countless documents to death and gleening no useful
information out
of a 50 to 100 page doc, I finally developed a procedure that works -- you set
up an interview with the SME and bang out an outline for the doc before it
ever
gets started. Using an outline as a constraint can really focus a SME on the
kind of information you need to have -- then wordsmithing actually does
some good!
You have to not be afraid to sound really stooooopid!
..So, what exactly does this product do? Can you give me an example of
when someone would use it? What would be the first thing they have to do
to get started? I'm sorry, I don't understand... Is that _really_ something
they have to know? Yes, but will they know how to do that, or do you have to
tell them how? Then what?...
So while they're sitting in my office playing with my hot pink plastic
Microsoft Slinky or scribbling on my Etch-a-Sketch Jr., I'm turning this
question-and-answer session into a real outline they can use as they write.
Once they've been initiated into the process, the engineers love it because
it saves them time. They can remain focused and just fill in the blanks, so
they don't add a whole lot of extraneous information. I get much more done
because I don't have to wade through 50 pages of "listen to how this baby
works" before I get to 10 pages of "here's how to use it" -- or worse yet,
never get to those blessed 10 pages at all.
