RE: Documentation Review Strategies

Subject: RE: Documentation Review Strategies
From: Karen Casemier <karen -dot- casemier -at- provia -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 26 Apr 2001 09:16:52 -0400

I receive the digest version of this list, so someone may have brought up a
similar point already, but here it goes...

I've found that I rarely, if ever, get the type of information I need by
just handing a chunk of documentation for someone to review (even if that
person is precisely the right person to review that type of material). The
majority of comments I get back are related to style/grammar issues, and are
not really about the content itself. I realize that some company policies
require this level of review, but if not, I suggest you bag that plan
altogether.

Instead, I either provide a specific list of questions, or a marked up
(highlighted with questions) chapter of the book. That way, the reviewer has
clear direction on the type of information I'm looking for. I can direct the
review towards the specific type of information that I need.

I liken the first type of review (simply providing an entire chapter) to
going to your SME and saying "can you explain how this program works", while
the second type of review (asking specific questions) is like going to your
SME and saying "are charges generated based on the Entered date or the
Received date?" The first type of question gives the impression that either
we don't have a clue, or we haven't put forth any effort to figure the
technology out for ourselves (either of which may actually be true - if you
are new to a company or to the field, you may not yet have the skills to
figure it out yourself - but that should be your goal). You also don't have
control over the type of information you get from that question.

Again, if your company policy requires a full review, then you don't have a
choice in the matter. Your best bet then is to spend some time educating
your reviewers as to the type of information you're looking for. But if not,
consider revising your strategy -- you can then get precisely the type of
information you need. Since I started using this approach, I've gotten much
better responses from my reviewers.

Karen R. Casemier
Senior Technical Writer
Provia Software
karen -dot- casemier -at- provia -dot- com


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

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

Sponsored by DigiPub Solutions Corp, producers of PDF 2001 Conference East,
June 4-6, Baltimore, MD. Now covering Acrobat 5. Early registration deadline
April 27. http://www.pdfconference.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: Re: Making them read the documentation
Next by Author: re: process templates
Previous by Thread: HTML Help and associated dlls
Next by Thread: RE: Documentation Review Strategies


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


Sponsored Ads