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.
Peggy Lucero wondered: <<After the developer finishes his
writing/delivering content, document then needs to go through peer
review and then be reviewed by the client. Each of these reviews is
likely to result in changes/deletions/additions/recommendations, etc.
all done in WORD with tracking changes on.>>
So far, so good. This is the core of an effective review process. The
trick is to minimize the number of iterations.
<<In the highly technical documents my part is mainly as an
editor/overseer for spelling, grammar, sentence structure, punctuation,
layout, format, etc.>>
Two key success strategies that I've used in the past: First, sit down
with the author before they begin writing and create a kickass outline.
I'm talking "blueprint" here, as in "you wouldn't build a house without
a blueprint, so why would you write a complex document without an
outline?" (This also applies to software engineering, but programming
managers seem genetically incapable of understanding this. <g>) Get the
outline approved by the managers before you begin writing and you'll
also see many fewer "you forgot a section" or "the logic here makes no
sense" comments later in the review process.
Second, if you eliminate all these types of error ***before*** you
begin the peer review, reviewers can concentrate on the technical and
political aspects of the review that they're best qualified to handle.
The more simple editorial matters they see, the more their attention is
drawn away from the actual technical aspects of the review and the
worse a job they do during the review. It seems counterintuitive to
devote all this effort to "perfecting" something that will be reviewed
and changed many times, but if you review the content (outline) and
style (editing) before the review, many fewer changes are required
after the review.
<<during the review process, how many times should I be reviewing the
document and making editorial changes?>>
As often as necessary. <g> Sorry to be glib, but that's the only
broadly applicable answer. The most efficient review process I've been
part of (and helped design) had me do the initial edit before peer and
technical and external review, and a final edit before page layout.
Then one last kick at the can when I proofread the layout. Two
editorial reviews is the inescapable minimum. The first one makes the
technical reviews effective; the second one fixes the errors introduced
by those reviews.
<<Boss says that after the client reviews document and makes their
recommendations document should not be changed.>>
There's a sound reason for this: it's surprisingly easy to introduce
significant errors into a document by making seemingly innocent changes
that change the meaning. If the client has done a good job of the
technical review, then the document will be technically correct and
that's by far the most important part of the review process--soyou
don't want to risk that status with an ill-considered edit. That's what
worries managers.
That being said, any decent editor will edit with a keen awareness of
the risk of changing the meaning, and will be scrupulously careful to
note any edits that might change the meaning. You can then discuss
those with the technical experts to ensure that they're correct. If you
can persuade your boss that this will happen, there should be no
problem with this final review phase.
<<Also, I am allowing 5 days, typically, for the peer review and 5 days
for the client review. Is that appropriate?>>
Review deadlines must be set based on two criteria: First, will the
reviewer be available when you send the document for review. Second, is
the length of the period sufficiently long for the amount of reviewing
that must be done?
I've solved both problems nearly 100% by building a "query for
availability and preferences" phase into the review process. Before we
begin writing, we identify the reviewers. I contact them to ensure that
they will be available around the predicted time when the documents
will be available, and identify all their relevant preferences (Word
file, PDF, faxed document, printed copy delivered by courier, etc.) and
how busy they expect to be (i.e., how long they need for the review
given their other duties). I then confirm their availability as the
deadline approaches.
After sending the review copy, I ask them to confirm they've received
the review copy with no problems and that the deadline is still
acceptable. I then add a note to my calendar software to remind me to
remind them of the deadline if they haven't yet returned the document.
Works amazingly (but predictably) well!
I have an article on designing an effective review process in the works
for _Intercom_, and hope it will appear early in the new year. In the
meantime, there's a bunch of helpful stuff on my Web site.
Now Shipping -- WebWorks ePublisher Pro for Word! Easily create online
Help. And online anything else. Redesigned interface with a new
project-based workflow. Try it today! http://www.webworks.com/techwr-l
Doc-To-Help 2005 now has RoboHelp Converter and HTML Source: Author
content and configure Help in MS Word or any HTML editor. No
proprietary editor! *August release. http://www.componentone.com/TECHWRL/DocToHelp2005
