summary: reviewers' guides (long)

[Jennifer Collins <jcollins -at- RIVERBEDTECH -dot- com>]

Here is the summary of replies I recieved concerning writing a "reviewer's
guide".  Thanks to everyone who helped me out.  I'm looking forward to this
project - a change of pace, if nothing else...

Definition: A reviewer's guide is 'a guide to be sent along with a product
to journalists and outside analysts, so they can judge the product'. (In my
case, the product is a software package.)

lynette -dot- wilkinson -at- ips-sendero -dot- com writes:
Jennifer, "Writing Software Documentation" by Thomas Barker has a whole
chapter on getting useful reviews, including sample questions. You might be
able to use some of this information to set up guidelines for reviewers. I
bought the book from Amazon books.

kimber_hebert -at- acs-inc -dot- com writes:
[Purpose:]
Well, the *marketing* department asked for the document-that's your first
hint
that this is not tech writing as we usually know it (if there actually IS a
'usual'). Your purpose here is dual: the main task of the Guide would be to
impress the Reviewer with the summarized, well-thought-out functionality of
the
software. The idea is that the Reviewer is impressed with the software even
before s/he tests it.
Your second priority in a Review Guide is to provide a common task list and
the
best way to perform those tasks. If your software has "ooh-cool" features,
make
sure that you include their use in the "common tasks."
[Audience:]
Sometimes reviewers <gasp> don't know all that much about the field that the
software supports, and sometimes they are industry experts. It would help
you to
know the reputation of the publication reviewing your product, and anything
about the reviewers. From my experience, I was able to find out who was
scheduled to conduct the review and get some bio on them from the
publication's
site. Your marketing department hopefully has some of that info, too. Ask
your
software development teammates what they think about the publication and
it's
reviews.
Then I suggest that you read some -reviews- rather than other Review Guides.
Find out what the result is, what the reviewers focused on, glean any sense
of
method or consistency that you can.
I don't know whether you have any constraints on file size, graphics, etc.
for
your Reviewer's Guide. I typically put in a few key screen caps, labeled.
And I
put in any sort of statistical information about our market that I can get
my
hands on (that also applies to the pertinent software). 
If the Reviewer's Guide is going to be prepared to send out to anyone that
will
review the software (as opposed for some known bake-off for a particular
publication) you should consider including whatever key INDUSTRY concepts
the
reviewer would need to appreciate before s/he could fully grasp how
brilliantly
your product is designed. You might want to embed these ideas anyway, just
in
case the reviewer forgets, or needs a perspective-shift.

bethkane -at- tcisolutions -dot- com writes:
I think such a guide needs to be particularly short and succinct.
Journalists don't have much time. OTOH, some of the journalists who write
software reviews are not run-of-the-mill reporters -- they're more like
propeller-heads. So you have to point them to the more dense reference
information too, to keep them happy. They just might read it on the train
ride to work.

ericsutherland -at- netscapeonline -dot- co -dot- uk writes:
The Rewierers Guide is a marketing tool and should describe the functional
and
business benefits at the top level. It might also show the a family tree at
this
level.
About 20 to 40 pages depending on the benefits the application or system
gives the
User.

bsullivan -at- powerware -dot- com writes:
I am a tech writer, but I have also written book reviews (am in the midst of
yet another one at present) and I have reviewed other artforms. 
So speaking as a reviewer, I would like basic information at the top of the
paper such as: Correct Name of the Product, Correct Version Number, Correct
Name and Addresses (postal, email, URL) of the Company. I would like this,
and more. Perhaps you could compare it to what you would want to find in a
catalog, or on a catalog card in a library if you were looking up a book. A
reviewer wants and needs all of this for reference. 
I would expect that the software product would be delivered to the reviewer
as a buyer might encounter it. In other words, I would expect it to come
with installation instructions. If not, then I would think you should
explain it in a straightforward and professional manner. One way to go about
this might be to say that this is an advance reviewer's copy of the
software. The delivery version will include the following installation
instructions, or the attached installation instructions.
I guess the key point here is to remember that a reviewer is a user's
advocate. The reviewer's job is to look at that package the buyer is
shelling out money for, and to evaluate it. So you want to give the reviewer
as complete and honest a picture of the buyer environment as possible.
I would also add a cup or two of marketingese. A list of the product
features with explanations could actually be helpful to a reviewer with
limited time. He might miss something.  I think you can understand the
difference between a professional presentation and a heavy-handed one,
however. 
And you might list the differences between the current version and the
previous one, in the name of usefulness to the reviewer and not providing a
snowjob.

christi -at- sageinst -dot- com writes:
Actually, at one of my former employers, a reviewer's guide was ...a
document sent to journalists who were going to review the product. At the
time, the doc was written by the PR dept. and I simply edited it.
One of the more important aspects was to point out new features. And not
just in a marketing-way, but in a somewhat more technical way. The
reviewers were usually pretty familiar with the platform and how to
navigate basic software. And if it was a new version of an already released
product, the reviewers usually had some experience with the previous
version.
I think what's usually provided is information about the benefits of the
product (yes, that's marketing), the important features (marketing, but in
a functional way), functions (extremely brief reference guide type info),
and comparisions to other products.
While you are hyping the product, they aren't buyers. You don't have it to
sell it to them in the same way as an ad. But you do have to make them
realize the benefits of the product. I think of it as a little less
technical than a white paper, but not full-blown marketese.
Now that I think more about it, I think this also depends a little on the
type of product. Is it hardware? Software? Is it really complex? Is it
pretty straight forward? Is it for general consumers? Or for a specific
niche (e.g., sys admins)? All of this would contribute to determing exactly
how marketing or technical to get and at what level.
You might also look at some reviews of products from some of the people
you'll be sending the guide to. That might help you figure out what they
might be looking for. And look at reviews of competing products.

---

Jennifer L. Collins
Technical Writer
Riverbed Technologies, Inc.
703.847.3303 x121
jcollins -at- riverbedtech -dot- com