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.
I used to manage a team of technical writers developing training
materials and your question came up repeatedly. When I first began, we
had no editorial process. A single review was supposed to be performed
after the student guide was completed, but inevitably, project schedules
had been underestimated and this critical review was permitted to slip.
When I took over, I started a review process nearly identical to what's
been described in the list so far. I think Joe Malin suggested a
"ranking" as to who has ultimate responsibility: Editor, Tech Writer and
finally, SME? Forgive my faulty memory...
The best approach, in my experience, is one that recognizes the
individual expertise of each team member on the documentation project.
My two cents?
The best editorial review consists of a round table meeting of the
minds. All team members are present: SME, Editor, Tech Writer and a
representative or two from the target audience, i.e., end users.
The Tech Writer facilitates this meeting. Each person present has
specific expertise. Tech Writers should be writing experts who know how
to grammatically construct sentences, paragraphs, and pages as clearly
and concisely as possible. SMEs are the technical experts. If it is
possible to have a few end users review a document, you'll find that
they help you plug gaps in writing and remove any assumptions the
project team may have made regarding prior knowledge. But Editors are
NOT responsible for the writing. They - in my opinion - SHOULD ONLY BE
RESPONSIBLE FOR ENSURING STANDARDS.
(I know - I'm likely to get jeered for this. I've found that when
editors are granted full responsibility for a document, the relationship
between technical writer and editor deteriorates into 'one-up-manship'
where preferences for second person over third, or gerunds over
infinitives, or even Arial over Times Roman prevail over what's best for
the end user. Because most editors are writers, it is natural to want
things written to preference. However, editors did not write your
document. They do not know the context within which you chose specific
words or phrases. They should never be permitted to make changes without
the author's and SME's approval. Granting editors full control often
introduces ambiguity to the finished document.)
The Editor should enforce compliance to your company or departmental
style and standards guide. Your guide should dictate the issues I
described above: what fonts, voice, and verb forms to use. In my group,
our style guide did that plus described preferred methods for
documenting the typical graphical user interface, i.e., is this called a
'window,' a 'screen,' or a 'dialog box'? It also contained a number of
instructional design principles we followed to assure learning
transference. The Editor was permitted to withhold sign-off until these
standards were evident.
The SME is the technical expert. This person has ultimate approval of
the message itself. If you say "MUST" in a step, the SME should be able
to tell you definitively that such language is right or wrong. The SME
should tell you what triggers the task, what is produced when the task
is correctly performed, what happens when it is incorrectly performed
and how to fix it.
During the review, typos, grammar issues, and even word choice are
likely to be challenged by any member of the team. This is fine and to
be encouraged. Change the obvious errors, but you, as the technical
writer, should retain control over the language. I used to bash heads
with my SMEs whenever they wanted to use invented words like
'clickable', 'downloadable' or 'rearchitected' in my documents.
Sometimes, such a word stayed in when a SME convinced me that it BEST
described what we wanted to teach, but even then, I retained the right
to define the word appropriately and use it sparingly.
If you have to do reviews one at a time, I suggest peer review, editor
review for standards, and SME review for technical accuracy. Once the
SME approval is in, that's it - document is considered frozen. If the
SME's review introduces language changes or issues that affect style, by
all means, confer with your editor again. If the SME finds only typos or
insists you should say 'that' instead of 'which', return the document
and reiterate the purpose of the technical accuracy review.
Wow...I've written a novel... end of my two...er twenty cents.
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
---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
