TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
>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.
