Re: Technical Review Guidelines

Subject: Re: Technical Review Guidelines
From: Mark Baker <mbaker -at- OMNIMARK -dot- COM>
Date: Fri, 11 Sep 1998 11:06:14 -0400

Thomas Quine wrote


>I'm enclosing a technical review cover sheet that I wrote - not because it
>is perfect, but because it needs improvement.

Your check list puts a lot of responsibility on the SME that properly
belongs on the writer.

> I have made sure this document contains all relevant information needed by
the user.

This is the writer's responsibility. It is the writer's job to understand
the user profile and know what is needed. SMEs typically want to include far
more than is needed.

> I have walked through every step-by-step procedure in the document,
testing it directly on-screen against the software being documented.

Very definitely the writer's responsibility. You can't expect the SME to do
this. If the writer has not done this, they have not done their job.
Ideally, the writer should also arrange for usability testing in which an
independent third party closely observes test subjects performing the
procedures.

> I have compared all screen illustrations in the document to the most
recent version of the software.

Writer's job.

> I have checked to ensure that the document is well-structured and its
content is properly organized.

Writer's job. This is outside the SME's area of expertise. Look at it the
other way round -- would you expect a writer to review a programmer's code
to make sure it is well structured?

> I have tested the index by looking for several topics at random.

Writer's job. This is purely about the mechanics of the document and has
nothing to do with technical accuracy.

> I have read the document from cover to cover.

Yes, the SME must do this. But you will make friends and influence people if
you develop an increments sign-off process rather than giving an SME a whole
book to read at what is probably a critical point in the development
process.

> I have indicated on the document itself, or on an attached sheet, all the
inaccuracies I could find.

Perfectly reasonable.

> I am confident that with the exception of the sections where I have made
comments, this document is technically accurate.

This is the one and only thing you can or should expect from an SME. If you
want a check list, break out various aspects of this point.

> I am confident that this document is well-conceived and will serve the
user well.

Documentation manager's job. Also product manager's job. Not SME's job.

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




Previous by Author: Announcing new STC St. Louis Chapter Web Address
Next by Author: Re: Posting Ken Starr's report to the Internet
Previous by Thread: Technical review guidelines
Next by Thread: Re: Technical Review Guidelines


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


Sponsored Ads