FW: Technical Document Evaluation

["Anna Langley" <alangley -at- ts -dot- checkpoint -dot- com>]

Dear Tech Writers:

Here's an additional comment from my team member, Courseware Developer
Barbara Vibbert:

John brings up valid points.
I made the suggestions working on the assumption that a
relationship exists between the writers and the reviewers.
(in the same building, working for the same company, etc...)
The feedback form should work, even in situations where no
direct contact between the writer and the reviewer is
possible. The feedback won't be as rich, but the writers
should still be able to identify areas for improvement.

Identifying good incentives for SMEs is a tricky business.
(Gross generalization warning) The SMEs are SMEs because
they know far more about the subject than the writers do.
In theory, the writers are better at communicating
information. However, the SMEs don't need the information
communicated to them; they already know it. Giving the SME
a credit, as a technical reviewer, in the book may be all
the reward some SMEs require.

Other Suggestions:
Give the SME a free copy of the finished documentation.
Give SMEs software/hardware for testing. Let them keep it.
Shirts, hats, and desk toys are usually well received.

If your writers have time, and direct communication between
the SMEs and the writers is possible, the writers can produce
documentation to help the SMEs do their job better, faster,
easier NOW. Here's how it works in my organization:

Writer: I'm writing a book about foo. I've been told you
use/support foo. What part of foo gives you the most trouble
or is the most difficult to configure?
SME: The bar procedure in foo is awful. If there's a way to
make that easier, my life would be full of sunshine.
Writer: I don't write the code, so I can't change how bar
works, but I can write detailed, step-by-step instructions on
the bar procedure; a cookbook, if you will. Would that be
helpful?
SME: Yeah, and maybe a checklist, so I can make sure I've done
all the parts.
Writer: Can I e-mail a draft copy of the instructions and
checklist to you when I get it done? Let you test it out, see
how it works?
SME: Sure... while your at it, make sure you explain fnord in
your foo book. I'm tired of explaining fnord to everybody
under the sun.
Writer: Do you have an electronic copy of your fnord explanation?
SME: Yeah, I had to send it to two people this morning. Mind if
I just forward the e-mails I sent to them to you? It's kind of
rough.
Writer: That would be great. After I put your fnord explanation
into our format, can I send you a copy? Maybe you can look it
over, make sure everything is still correct and makes sense?
SME: No problem.

In the scenario above, the writer gets a SME to review the
documentation he's generating. The SME gets detailed documentation
for a procedure and a check list (job aid). The writer gets an
expert's explanation of a topic, and the SME gets a clean version
of the explanation that he can use in stock messages.
YMMV, but my experience is that if you tackle what the SMEs hate
most first, help is forthcoming for other projects.

Barb


>>...Consider a feedback form where the evaluator rates...
>>...Provide space for the reviewer to comment....
>>...Ask the reviewers to suggest resources

> jeezz...I gotta do all this work for you to do YOUR job better? What's in
it
> for me, and I hope it's not the knowledge that I'm contributing toward a
> better SME who I've never met, and I don't even know if there is a real
> person on the other end of this survey form...I mean real stuff. Knowledge
> that by participating in this evaluation, I'm going to be able to use the
> existing documentation better to do my job better TODAY OK, if not, how
> about Money or Women (or men).

John Posada
Senior Technical Writer
Barnes&Noble.com
jposada -at- book -dot- com
NY: 212-414-6656
Dayton: 732-438-3372
Although she lives with seven other men, she's not easy.
------ Magic Mirror


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Purchase RoboHelp X3 in April and receive a $100 mail-in 
rebate, plus FREE RoboScreenCapture and WebHelp Merge Module.  
Order here: http://www.ehelp.com/techwr-l

   Help celebrate TECHWR-L's 10th Anniversary starting this month!
Check out the contests at http://www.raycomm.com/techwhirl/special/contests/
Happy birthday to you, happy birthday to you, happy birthday TECHWR-L....

---
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.