Re: Editorial and technical reviews

[Paul Branchaud <paul -at- VEDGE -dot- COM>]

On Wed, 29 Jan 1997, Sue Heim wrote:

> matter). Some of the program works, some doesn't, and some doesn't
> exactly work like it's supposed to. Typical, yes?

Same old song and dance. ;)

> OK, the problem. I really need to have the programmers do an initial
> review of the online help -- a *technical* review first.

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."

> 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.

> What to do? Do I try to stand firm, and try to explain myself once
> again? Or do I let them do the editorial review now. I'm afraid that
> if they do the editorial review now, they'll concentrate less on that
> aspect later.

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.

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.

Part of the problem may also lie in the presentation of printed online
help. I create my online help the "hard way" by starting from scratch with
RTF files. The resulting layout is linear and makes sense to me, but
programmers always say it's hard to read. I explain that in my memo as
well (that it's not meant to read like a book) and ask for the careful
attention, given the layout.

When it comes time to do an editorial review, I usually ask my audience
(via a memo) to read the printed version alongside the online product.
This way, editorial comments reflect the actual on-screen presentation of
the help system.

Best of luck!

Paul
**************
Paul Branchaud (paul -at- vedge -dot- com)        "What kind of Mickey Mouse outfit
Technical Writer                        names their team `The Ducks'?"
Visual Edge Software, Ltd.       Bugs Bunny to Daffy Duck in Space Jam
 **The Surgeon General has determined that the above-stated opinions
 are loopy and should not be inhaled or otherwise taken to be fact**

 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