Re: more on peer reviews

["Susan W. Gallagher" <sgallagher -at- STARBASECORP -dot- COM>]

Becca Price wants to know...

> We're a small group of widely varying abilities and experience (from 18
> months at most charitable to about 6 years to 18+ years).  We desperately
> need to upgrade the quality of our documents, and to smooth out our group
> style.  Review meetings seem to be an answer, but I have some questions for
> Sue Gallagher, Boni  Grahm, and the others who contributed to discussion on
> peer reviews:

> Is this strictly a *writing* review, or do SMEs contribute?  or do you have
> separate technical review meetings?  if it's all done at once, how do you
> keep the technical people from being bored out of their minds when you get
> into a discussion of a subtle point of technical writing?

Actually, I have never organized either a peer *edit* or a technical
edit/review into a bona fide meeting. In the interest of time, it's
best to keep things moving, and meetings tend to slow things down.
I've always liked a 'round-robin' approach to peer editing. Just pass
the document (or piece of it) around until everyone's seen it -- and
advise everyone to use a unique ink color for their comments.

Letting others see what their collegues have commented on, and letting
them see comments on comments, will really smooth out the group style.

But, whether you do this or actually have a meeting, keep it separate
from the technical review. It's a totally different subject and needs
to be treated as such.


> if you have a separate technical review meeting, who attends?  and how do
> you enforce attendance?  (for example, we're getting excited here at the
> idea, since we have trouble pulling in comments *before* release - but if
> developers won't even read the doc. to review it now, how do we get them to
> come to a meeting having read it already?  and if they come and haven't read
> it, do we send them home and say "sorry, you lost your chance to tell us
> whether it's accurate or not?"

I've never worked for a company that sanctioned technical review meetings,
so I guess I don't have a lot to say here. I've always taken either the
'round-robin' approach or just doled out a copy to each reviewer. Making
sure that you have overlap on expertise (if it exists) helps ensure
accuracy when reviewers don't read the doc or when the just miss something
because they're busy.

> if you do have a technical review meeting, should you have a PC in the
> meeting room to access the software being documented?

> also a question on time: we frequently don't have the luxury of time here
> (very bad planning, we're working to change things, but is is) - at best, we
> have our communications room do the photocopying the night before the
> software goes live to our in-house users.  sometimes we don't even see the
> software until it goes live to our in-house users.  We don't have the time
> to use our in-house pubs room for high-quality duplication.  *when* in the
> process is it most efficient to have an editorial review of the document?
>  just before it goes to press? after the first draft is finished, and hope
> there are no induced errors?

Oh, that's a tough one -- because there's no one right time. It
depends on the doc and the staff and so much more.

I'd say that for now, while you're getting started and writing
styles are still 'anything goes', you'd want to review/edit the
docs after the initial draft (to check organization and overall
style) and again just before final layout to make sure that
no errors have crept in.

Once the process is up-and-running for a while, scheduling
peer edit for after tech edit and before final layout seems
appropriate (theoretically, your styles will be merging so
there won't be so many changes later in the process ;-)  )

Hope this helps.

Sue Gallagher
sgallagher -at- starbasecorp -dot- com