Re: Technical Review Guidelines

[Kathy Graden <kgraden -at- MAIL -dot- DANCRIS -dot- COM>]

Mark, I agree with most of your comments, but you seem to expect too much
of the writer in some instances.  (See comments below.)

At 11:06 AM 9/11/98 -0400, Mark Baker wrote:
>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.

The writer should be at least 95% accurate about what information is
needed.  But unless the writer has extensive technical expertise himself or
herself, he or she may inadvertently overlook a few details that the user
needs to know.  In addition, if a writer has been getting most information
from one or two SMEs and the document is being reviewed by another SME, the
third SME may know something the others don't.
>
>> 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.

"Ideally" is the keyword.  How many of us have resources or time for formal
usability testing?  I know I sure don't.    I check out procedures in my
documents as much as I can.  But often in my company, the engineers make
changes up until the last second.  So even if I diligently test a procedure
one day and get it 100% right, engineers' changes can make my procedure
obsolete the next day.
>
>> I have compared all screen illustrations in the document to the most
>recent version of the software.
>
>Writer's job.

Yes, but again, recognize that last-minute screen tweaks and bug fixes can
change things.
>
>> 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?

Excellent point.  However, if the user must perform certain tasks in a
certain order, the SME should verify that the document presents those tasks
in the proper order.
>
>> 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.

True.
>
>> 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 ask each of my SMEs to review specific parts of a document.  But I give
them a complete copy of the document to enable them to see the part they're
responsible for reviewing in its proper context.  And I invite the SMEs to
review other sections of the document if they want to and/or have time.
>
>> I have indicated on the document itself, or on an attached sheet, all the
>inaccuracies I could find.
>
>Perfectly reasonable.

Yes, it's reasonable.  At my workplace, though, SMEs don't just return
marked-up review copies to the writers.  The writer and the SMEs sit down
at a review meeting and hash out details of how to fix what's broken in the
doc.  One of my pet peeves is when an SME indicates that something in my
document is wrong, but doesn't provide or point me toward the information I
need to correct it.  Therefore, I always ask my SMEs to bring to the review
meetings either the information I need to make the fix, or the name of the
person I should contact to get the needed information.
>
>> 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 would probably revise the review cover sheet to have the SME say, "To the
best of my knowledge, this document is technically accurate."  Not all SMEs
can verify all technical information in a document.
>
>> 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==
>
>
>
>

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