Peer Reviews

[Gwen Barnes <gwen -dot- barnes -at- MUSTANG -dot- COM>]

-> QUALITY FIX (Band-Aid (tm) )  :
->
-> We have been attempting to improve quality the cheap way:
-> having other writers review each other's manuals. So far,
-> not much has been accomplished.

-> Have any of you experienced successful peer review
-> operations? Unsuccessful?

It has its pitfalls. Under time constraints, I passed a draft copy of a
600 page manual, along with a marked-up proof from engineering, to a
colleague to make the required changes. Most corrections were of a
technical nature, with a few minor proofreading things as well.

My colleague took it on himself to rewrite substantial portions of the
book having nothing to do with the specific engineering comments, and
thus introduced obfuscations and technical inaccuracies which I then
had to correct -- a year and a half later I'm still finding
"nolanisms" in my book. I was not sorry to see him leave.

I would do this again ONLY if I was assured that a colleague was
technically qualified, not only in terms of the product being
documented, but in basic writing skills. Even then, the basic writer's
urge to "fix things" will probably result in acrimony.

-> Are we hopelessly Out To Lunch on this approach?

Not if you trust your colleagues' judgment absolutely. Otherwise I can't
think of a more effective way to undermine any sort of "team" atmosphere
you've tried to build.

What has worked better for us is to let a select number of our beta
testers review near-final drafts of the documentation in hard copy, with
very specific instructions about their task, including clear deadlines
for returning correction pages. We made this easy on them by asking
them to write their changes directly on the page concerned, and letting
them fax back only the changes.

I was dubious about this at first, but the last project we did this way
went very smoothly, and I got valuable feedback and insights from
end-users. Think about it ... who's going to be using the product, and
the manual -- one of your fellow writers, or, hopefully, a lot of your
customers? Whose feedback therefore is going to be more valuable?

Cheers,                                                 @DISCLAIMER@
Gwen                                         gwen -dot- barnes -at- mustang -dot- com
MSI * Connecting the world                              805-873-2500