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.
Subject:Re: Editorial and technical reviews From:Sue Heim <sue -at- RIS -dot- RISINC -dot- COM> Date:Wed, 29 Jan 1997 11:12:12 -0800
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.
> > My boss wants the programmers to do both an editorial and
> > technical review.
> 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
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
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!
Research Information Systems
Carlsbad, California USA
Email: Sue -at- ris -dot- risinc -dot- com