Re: Editorial and technical reviews

[Sue Heim <sue -at- RIS -dot- RISINC -dot- COM>]

To my plea:
> > OK, the problem. I really need to have the programmers do an
> > initial review of the online help -- a *technical* review first.
Paul Branchaud wrote:
> I find that early technical feedback is *very* important to the
> success of my online help; it helps to define what tweaks I need to
> make to the format of the help to make it as useful as possible to
> the end users. I usually have to beg and plead to get early
> technical feedback that goes beyond "Read the technical
> specification, it's all in there."

And that's why I was asking for simply a technical review. I really
don't know if I'm in the target area or not, and much of what I'm
writing about doesn't even work properly now. Without true specs, I'm
really shooting in the dark here.

Me:
> > My boss wants the programmers to do both an editorial and
> > technical review.
Paul:
> Before I read that you are the lone writer, I cringed at the thought
> of programmers doing an editorial review. Unless they have previous
> writing experience, I usually find that programmers do not
> understand documentation issues well enough to offer truly
> constructive editorial comments. No matter how often I tell them
> that I only want a review for *technical* accuracy, I invariably get
> editorial comments as well. I keep the useful ideas and set the
> other comments aside.

Nope, none of them have writing experience, although they *all* seem
to think they can do my job better than I can! I usually will
incorporate valid comments, and ignore the rest. But then we get into
a real pissing match, cause they are adamant that their comments --
good or bad -- be included. As if they listen to me on the user
interface! <grin>

Then Paul offered:
> What I usually do, to stress my point to the intended audience, is
> to include a memo as the top sheet for the material I am asking them
> to review. The memo contains, in clearly defined terms, what I
> expect from the receipients (ie: no editorial comments, just check
> the technical accuracy) and when comments should be returned with
> their "seal of approval" or corrections.

This doesn't work. No matter how many times I write, highlight,
enlarge, or beg.

> You may want to try this, but bosses can be bosses, and you may have
> to bite the "editorial bullet" early on. I have found that technical
> reviews are usually faster and require less of the programmer's time
> than when they decide they will be judge, jury, and editor all in
> one.

And duh! That's the gist of the matter. I need feedback NOW, quickly.
I can wait on the editorial stuff cause sheesh! *I've* not really
even done an editorial review of my own stuff yet!

Thanks for your comments, Paul!
...sue
-------------------------
Sue Heim
Research Information Systems
Carlsbad, California USA
Email: Sue -at- ris -dot- risinc -dot- com

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html