TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
From the Editor’s desk: 1-3
In Focus: 4-7 Tools: 8-13
Directions: 14-16 Reflections: 17-21
Legally Bland: 22-24 Confessions: 25-29
The Master Speaks: 30-37
Spotlight: 38-42, 43-47
Writer of the Month: 48
April 2009 Document Review Special Issue Volume 41
F R O M T H E E D I TO R ’ S D E S K ( G U E S T
S t ay i n g S a n e w i t h S a n i t y C h e c k s
We’ve all heard of, and most likely experienced the full brunt of Murphy’s Law
sometime or the other. You know that anything that can go wrong, usually does. How
many of us have reviewed, peer reviewed, and then re-reviewed a document just that
S umedh is a senior technical
writer and trainer. His
one extra time, to realize that you’ve forgotten to update the copyright year, a day
after the document was picked up by the final build? Unfortunately, this is more
WordSmiths, offers technical common than is necessary, and I say it doesn’t have to be that way. It does need to be
writing and training services to managed, however. I’m going to explore the Sanity Checks as a way of filtering out the
clients in India, Canada and the unseen errors, even after the review cycles are complete. I will do so in form of some
United States. During his career, most likely questions.
he has worked in Europe,
Australia, India, Singapore, and
the United States. He has • We are a team of several writers, developers, and QA engineers with a
recently relocated to Toronto, solid review process. Aren’t sanity checks just a big overhead for me?
Canada. He has a rich experience
of nearly 15 years in all aspects of
documentation life cycle from No, they are not. Your review cycles will take care of typos, grammar, missing
design to implementation in content, and inaccurate technical details. However, sanity checks catch errors that,
software and high-tech
as a writer, are your responsibility. They ensure certain things that are not part of
environment. He can be
contacted at any reviews, don’t fall through the cracks. I will address these in the next question,
firstname.lastname@example.org. but if you are like most writers, you are probably multi-tasking to the fullest—
working on several guides simultaneously, getting feedback from numerous
reviewers on several documents, all at the same time. As you scramble to
incorporate all the feedback in time for a major build, it is but natural to forget
this, that, and the other in all the commotion. However, you can save yourself
from going insane through sanity checks.
F R O M T H E E D I TO R ’ S D E S K
• What should be the scope of sanity checks and any tips on managing them?
There is no single formula for a successful sanity check. Every writer in your team should prepare his/ her own
sanity checklist. List all the individual tasks you need to perform on a single document from start (planning) to
finish (deployment). Include in this list any step you know you consistently forget. For example, many writers
forget to update the Table of Contents (TOC) while rendering the finishing touches to a document. This is not
such a big concern half way into the release, but not very nice when it happens in your final check-in for a major
release. Another thing writers often forget is updating copyright year, build, version numbers, and the likes. Each
of these should be on your checklist as separate entries that you actually check off as done, as you go along the
list for each document in your docset.
You can be a little creative and enhance the effectiveness of sanity checks by doubling them as a status check.
Use them as a dashboard for the health of your document plan: reviews completed and pending, reviewer’s
name, percentage complete of each guide in your docset, index markers included, draft markers removed,
EULA updated, and so on.
You can use the following sanity checklist to start with and enhance it as you progress through your career. The
idea is to capture everything you need to do to make your guide as useful as possible for your readers. Add,
modify, and delete from it on an ongoing basis. I would strongly recommend you build a master checklist and
customize it for every project or document you work on.
Figure: A Sample Sanity Checklist
“There is no single formula for a successful sanity check.
2 Every writer in your team should prepare his/ her own sanity
F R O M T H E E D I TO R ’ S D E S K
• What is the right time for sanity checks?
Sanity checks should be the last item on your to-do list before checking-in the final version of your guides and
documents into your versioning system. Make sure you are through with all your planned review cycles, have
incorporated all the comments, and have received a signoff on the linguistic and technical accuracy from people
concerned before you go through your final sanity checklist. Ideally and depending on the size (length) of the
document, set aside 1-2 days for the sanity checks per document. You are very unlikely to need this much time,
but since time is never on the (technical) writer’s side towards the end of a release, it can come in very handy,
If you are a new writer, it is best to build sanity checks into your system now so they become a habit. If you are a
more mature writer but have somehow kept your distance, now would be a good time to get cozy with them.
~ Sumedh Nene
“If you are a new writer, it is best to build sanity checks
into your system now so they become a habit. If you are
a more mature writer but have somehow kept your
3 distance, now would be a good time to get cozy with
“ M a k i n g a M a r k ” a s a Te c h n i c a l
Editor or Reviewer
Many members of the technical communications fraternity fret over their career
progression, especially when managerial positions are few and in the passing. If involved
in such a discussion, I usually assert that the next logical step for a technical writer or
T his article is written by
Aneesha Myles Shewani, a
Lead - Technical Editor with
author is to become a technical editor or reviewer. I take this stand by reflecting on
two prominent aspects: first, the significance of review and editing for quality
Fiserv, Noida, India. She has a deliverables in documentation, and second, the recognition of reviewing and editing as
rich experience of nearly 9 years, a competency that is developed and enhanced over a period of time.
having started her career with
content writing for Times
I believe that the field of technical review and editing is not only professionally
Internet Limited, and then moving
into technical documentation for rewarding but also adds immense value to technical documentation. It is a benchmark
organizations like Infogain and for a writer’s maturity and competency, and also a position of immense responsibility.
Computer Sciences Corporation. Contrary to popular myth, editing is not only about marking corrections, or
She has worked primarily in the faultfinding; it is about total involvement in a documentation assignment, including
domain of insurance and risk
management, and payment and planning, collaborating, and defining best practices.
industry products. Apart from
being extremely passionate about The responsibilities of a technical editor include:
technical writing and editing, as a
profession and an art, she also
has a penchant for creative Planning
writing and regularly maintains • Understanding the aim and audience of a documentation assignment
her blog. In January 2009, one of
her works of fiction, “The Muse”
was published in “The Eleven”, a
collection of short stories by
bloggers, giving further impetus
to her love for reading and
• Planning for a documentation assignment, including styles, standards (editorial policy), templates, content, table of
content, and approach
• Defining the review strategy, such as creating review checklists and defect log templates
• Identifying technical, functional, and peer reviewers (in those cases where the documentation team size is limited
or the team is yet to evolve into distinct hierarchical roles, such as a manager’s role)
• Coordinating the efforts and activities of all the reviewers and collating various review comments
• Mentoring new technical writers to bring them up-to-the-mark with the editorial policies and standards
• Ensuring adherence to a defined “editorial policy”
• Maintaining timelines
• Restructuring content, making it more readable and organized
• Writing for some specific sections like overview, or samples for the team to follow
• Undertaking editing tasks, such as checking grammar, general word usage, spelling, and language-based edits
• Checking the technical and functional accuracy of the content (in consultation with a subject matter expert (SME),
or by referring to the collated review comments of the technical and functional reviewers)
• Testing the document, which means running the procedures in the document against the actual product to ensure
that the procedures are accurate and the end-user is able perform an action by following the steps
• Preparing a best practices document based on the defect logs
• Analyzing defect logs and preparing strategies for reducing defects and improving the document quality
“I believe that the field of technical review and editing is not
only professionally rewarding but also adds immense value to
technical documentation. It is a benchmark for a writer’s
5 maturity and competency, and also a position of immense
The planning, collaborating, and analyzing responsibilities provide on-the-job training for a documentation manager’s
role. It opens one’s perspective to challenges of good documentation, the need and pressure of working with various
stakeholders within specified deadlines, collating and analyzing data to generate appropriate metrics, and most
importantly, accountability for the quality of a deliverable.
With regard to the responsibility of writing, a good technical editor can be a fine mentor by showcasing good writing
samples or depicting through actual writing, what is expected from the technical writers. Vague marks, comments, or
even suggestions can only compound the writer’s confusion, especially if the writer is new. A good editor can always
rewrite some sections or sentences and provide positive reinforcement to the writers by giving them examples to
follow. Many technical writers get promoted to editorial and reviewer roles and their greatest asset is the knowledge
of a particular product or domain and hence, they can immensely contribute to a document by writing the descriptive
sections or adding to the information provided by the writer.
The challenge in the current industry scenario is to recognize the significance of technical editing and reviewing.
Documentation teams have to move from methodologies based on self-review and peer-review to a more
professional approach, where technical editing is developed as a competency. Organizations, which want to witness
serious and substantial growth in their technical documentation portfolio, should focus on creating a level for technical
editors in their designation-competency matrix.
Talking in terms of challenges, there is another that waylays the enthusiastic technical editor or reviewer—resistance
from within the documentation team. It is a fact that not many people are open to scrutiny and defect-identification in
their writing. Most technical writers are used to working independently, and as is typical to writers of all genres, deem
what they have written as correct, precise, and comprehensible. With due respect to all technical writers, the other
fact is that we all make mistakes!
If you are a technical writer, you cannot deny that there have been times when you revisited a document and caught a
little mistake here and a tiny glitch there, or just muttered under your breath, “I wish I had more time to self-review this
document, but for that ghastly deadline ….!” It is here that a technical editor can be your knight in shining armor and
help you eliminate oversight, improve the usability and quality of documents, and provide you a handy reminder of
errors and mistakes that you can easily eliminate in your next deliverable.
“A good editor can always rewrite some sections or sentences
and provide positive reinforcement to the writers by giving
them examples to follow. Many technical writers get
promoted to editorial and reviewer roles and their greatest
asset is the knowledge of a particular product or domain and
hence, they can immensely contribute to a document by
6 writing the descriptive sections or adding to the information
provided by the writer.”
You remain in-charge of your document with the safeguard of a professional edit and review. The better your track
record as a technical writer, the better your chances of becoming the technical editor or reviewer for a
On the whole, successful editing is dependent on the organization’s culture and the editor’s relationship with the
writer. The culture can provide a status, an authority, and a progressive growth path to a technical editor or a
reviewer. Collaborative team spirit shared with the technical writer(s) provides motivation to the editor, and supports
the symbiotic relationship between the writer and the editor. The end define the means, and whether it is the writer
or the editor, the true stalwart of technical documentation has only one aim—to deliver the right information to the
right people in the right way!
~ Aneesha Myles Shewani
“The better your track record as a technical writer, the better
7 your chances of becoming the technical editor or reviewer for
a documentation team!”
TO O L S
A n I n t r o d u c t i o n t o D I TA
Darwin Information Typing Architecture (DITA) is an XML-based data model for
creating topic-based content that can be reused and single-sourced in a variety of ways.
It was first developed by IBM in the 1960s. In 1999, IBM, Lotus, and Tivoli developed a
S hashi Prabha studied to
become an Electronics and
cross-company DITA architecture. When DITA was released as a public XML standard
in 2001, IBM contributed the DITA Open Toolkit, the first DITA-compliant processor.
Communication engineer, but In March 2004, IBM donated DITA to OASIS (Organization for the Advancement of
luck had better plans in store
Structured Information Standards), where it is now managed by the OASIS DITA
for her. She has a Bachelor of
Technology degree from Technical Committee. In April 2005, OASIS approved Version 1.0 of the DITA
N. I. T. (formerly known as specification.
R. E. C.), Surathkal. After
graduating, Shashi decided to
expand her skills and Overview
knowledge by working as a The name “DITA” has been derived as follows:
faculty member at Aptech, • Darwin: Named after Charles Darwin because the topics in DITA can be
Chennai. Later, she worked as
specialized to inherit properties of the basic topics.
a technical support
executive at CLi3L e-services • Information Typing: DITA was designed for technical information based on
Limited, Bangalore. She built information architecture of Concept, Task, and Reference.
upon her experience by
• Architecture: DITA is a model for extension of both design and processes.
diversifying into technical
writing—beginning with a brief
stint at TCS, Bangalore. At
present, Shashi works at
Integra, Bangalore, where she
is involved in the
documentation of mobile
Her primary interest lies in
TO O L S
Writing in sections is the traditional way of handling information. Creating DITA content consists of writing “topics”
and “maps”. A “topic” in DITA is a unit of information which is meaningful when it stands on its own. Topic files can
have the .dita or .xml extension. Topical writing does not imply any structure at the start. Nor do authors have to
consider how all sections will be nested properly. Topics can later be nested and linked in a separate navigation map
describing the context of all topics.
The following are three basic topic types in DITA:
• Task: Task topics describe the steps of a particular task, or provide an overview of a higher level task. They
should not describe conceptual or reference information. A single task topic should describe how to do one task
only. The structure of a task topic is as follows:
• Concept: Concept topics introduce the background or overview information for task or reference topics. They
should not describe task or reference information. A single concept topic should explain one concept only.
“Topical writing does not imply any structure at the start. Nor
do authors have to consider how all sections will be nested
9 properly. Topics can later be nested and linked in a separate
navigation map describing the context of all topics.”
TO O L S
The structure of a concept topic is as follows:
<section> | <example>
• Reference: Reference topics provide quick access to facts. They describe product features, commands, and so
on. Information needed for deeper understanding of a reference topic or for performing related procedures
should be provided in a concept or task topic. They should be designed for quick scanning of information using
lists, tables, and so on. They should not describe conceptual or task information. A single reference topic should
explain one subject only (for example, explain only one command). The structure of a reference topic is as
“Reference topics provide quick access to facts. They describe
product features, commands, and so on. Information needed
for deeper understanding of a reference topic or for
10performing related procedures should be provided in a
concept or task topic.”
TO O L S
DITA maps assemble topics into a coherent set for documentation deliverables. They have the ability to reuse and
repurpose the same content for different deliverable types and deliverables for different audiences and products.
DITA map and topic documents are XML files. Any images, video files, or other files that need to appear as output are
inserted as references. Any XML editor can therefore be used to write DITA content, with the exception of editors
that support only a limited set of XML schemas, such as XHTML editors.
DITA is integrated into and actively supported by many state-of the-art XML tools, such as Epic Editor, XMLSpy, Serna,
WorldServer Open Topic, and Content Mapper.
Maps can include DITA topic (.dita) files, XML (.xml) files, HTML files, PDFs, and more. The same topic can be
referred to more than once in a map or in different maps. Maps can be nested into other maps to build
documentation deliverables. They can be combined together manually or use scripts during the production process.
DITA map files have the .ditamap extension.
The structure of a DITA map is as follows:
DITA maps separate content from context. They build a relationship table to generate “related topics” links and set
properties of the topics at positions within the hierarchy. They also provide multiple views on the same topics: by
product, by task, by topic type, by audience, and so on.
“DITA is integrated into and actively supported by many
11state-of the-art XML tools, such as Epic Editor, XMLSpy,
Serna, WorldServer Open Topic, and Content Mapper.”
TO O L S
Some key features of DITA include:
• Topic-based architecture: Since DITA uses topic-based architecture, it allows you to produce smaller chunks
of content as compared to the traditional form of documentation. This helps in reducing documentation time and
• Content reuse: DITA helps you to reuse the topics in different deliverables.
• Specialization: DITA lets you define your own topic types from existing ones.
• Multiple output formats: The DITA open toolkit released by IBM helps you to convert the content developed
in DITA into various formats, such as:
− Microsoft Compiled HTML Help
− Eclipse Help
− Java Help
− Oracle Help
− Rich Text Format
• Easy topic search: Since DITA includes extensive metadata, it enables users to find topics easily.
DITA Open Toolkit
The DITA Open Toolkit, or dita-ot, is a free and open-source implementation of the OASIS DITA Technical
Committee’s specification for DITA DTDs and Schemas. It transforms DITA topics and maps into PDF, HTML, and
Online Help. A very helpful section within the DITA toolkit is the demo section. It consists predefined specializations
for a varied set of applications; for example, the bookmap contains many already defined elements required for a book
structure, like cover, preface, chapters, and appendix.
The toolkit continues to be the foundation of most DITA content publishing. Many DITA users use it directly, and
some DITA authoring tools and content management tools now integrate parts of the toolkit into their own
“The DITA Open Toolkit, or dita-ot, is a free and open-source
implementation of the OASIS DITA Technical Committee’s
12specification for DITA DTDs and Schemas. It transforms DITA
topics and maps into PDF, HTML, and Online Help.”
TO O L S
A reference implementation toolkit for both the developerWorks and OASIS 1.0 versions of the DITA DTDs/
Schemas is available at the DITA Open Toolkit project site on SourceForge: http://dita-ot.sourceforge.net.
~ Shashi Prabha
“A reference implementation toolkit for both the
developerWorks and OASIS 1.0 versions of the DITA DTDs/
13Schemas is available at the DITA Open Toolkit project site on
A B u g ’ s L i f e : H o w t o M a k e Yo u r
E d i t o r ’ s L i f e — a n d Yo u r s — S i m p l e r
What the heck are you talking about?
Yes, this article is inspired by the animation movie with the same title.
T his article is written by
Sridhar Machani, a
technical communicator at
In many ways, a technical communicator works like a bug (or an ant). For instance,
there’s a line (style and authoring guidelines) that you must stick to. As soon as you
Siemens PLM Software, Pune, deviate, a supervisor (editor) beats you back to the line (conform to standards).
India. He is part of the editorial
team of INDUS, STC India
Chapter’s newsletter. Sridhar Thankless Job
is also an active blogger. He For most people, an editor’s is a thankless job. You get credit for good writing, but an
maintains a popular blog on editor gets brickbats if something goes wrong. He/ she is doing his/ her job, that is, to
technical communication. You identify and point out your (writer’s) errors. He uses editorial markups, and to make
can read his blog posts here.
matters worse, the markups are in red. Would you like someone hovering around you
all the time—ready to paint your work in red? Did you say, “Aye?” I didn’t think so.
An editor is a shared resource. He often works at a hectic pace around tight deadlines.
Without his stamp of approval, not a single word can be published. It’s easy to blame
him for an error that has slipped through.
In hindsight, between you and your editor, there’s a common goal to conform to the documentation standards. He’s
helping you fine-tune your work. In short, he tries to ensure your writing helps customers better in their hour of
You need to realize this common goal and be professional in your approach. You may not agree with him, but that
doesn’t mean you and your team treat him like an outcast. Contest and argue with the markups, not the person. Be
humble and accept your mistakes. He’s your guru.
Often, editors are taken for granted. You write and push your stuff across to the editor and then consider your job as
done. Guess what? You can do more. For starters, provide sufficient heads-up to your editor about the product
release milestones and documentation deadlines. It helps him allocate time (when and how much) to review your
Every time you send something for review, let him know the priority—can you wait for a day, a week, or do you need
the review/ comments in an hour? Don’t assume that your editor is waiting to get started on your work as soon as
you send it in. That’s hardly the case.
All writers edit their writing to some extent. While you’re at it, ensure you keep an eye on standards and procedures:
they’re there for a reason.
Before sending out stuff to the editor, review your work at least twice—both in the source files and in the generated
output (PDF or HTML).
Mistakes appear often. Keep tab of the mistakes you tend to commit. Do a quick Google search; understand the
nuances of the right usage. Don’t make that mistake again (at least, try not to).
You may learn a few editorial tricks from Carolyn D. Rude’s Technical Editing (Fourth Edition).
“Contest and argue with the markups, not the person. Be
humble and accept your mistakes.”
A Simple, Happy Life
~ Sridhar Machani
“All writers edit their writing to some extent. While you’re at it,
ensure you keep an eye on standards and procedures: they’re
there for a reason.”
How to Evaluate Entr ies
Every year I have to instruct judges in our local STC technical communication competition on
how to evaluate entries. Here is what I tell them:
When you evaluate entries, wear your audience hat. That is, determine the audience of
R ichard Mateosian began
his career as a
mathematician. He earned a
the entry, and then try to think like a member of that audience. Entrants provide
information about the audience and purpose of their entries. Read this carefully, and
supplement it with your own understanding.
PhD in math from UC
Berkeley in 1969. Starting
while he was still in graduate With the audience hat firmly on your head, decide what the entry ought to accomplish.
school, he spent about fifteen Ask yourself what information it should contain, what navigation it should provide,
years as a programmer and
what it can assume and what it should explain, and so forth. The answers to these
systems development manager.
In 1979 Richard wrote questions become the basic framework within which you view the entry. Base your
Programming the Z8000, evaluation on how well the entry communicates within that framework.
which launched him into ten
years as a technical marketer
for high-end microprocessors. Having established a judging framework in this way, you can look at the STC criteria
Since the early 1990s, Richard for entries of this type to help focus your attention on details, but always remember
has worked exclusively as a that the big picture is more important than details. Your objectives in evaluating the
technical communicator. He entry are:
specializes in writing for an
audience of programmers. He • Recognize and provide positive feedback for the ways in which the entry succeeds
is active in STC, where he has in meeting the objectives you set for it.
been part of the Berkeley • Identify, and spell out ways to improve, areas in which the entry falls short
Chapter leadership for many
years. He has also been active of the objectives you set for it.
in the Northern California
A Guide to Writing Useful Comments
When you write comments, you change hats. Begin by putting yourself in the entrant’s place and asking, “What
feedback would I like from a colleague sitting with me and helping me ensure that my work meets the needs of my audience?”
The main point of the comments you write is to provide valuable feedback to entrants. Imagine that you are
responding to a colleague who has asked for your opinion on an important documentation project.
Write as though you are speaking directly to the entrant with the entry in front of both of you, but express yourself
as clearly and carefully as you would in a paper for publication. Judge your own writing as you would judge an entry.
Try to make your comments into a Distinguished Technical Communication.
You are an anonymous judge, and you probably don’t know all of the people who will read your comments, so the
personal connection that might make humor work is largely absent.
Follow the Golden Rule
Above all, write as if you were telling this information to a colleague, face to face. Don’t be snide, sarcastic, or unkind
in any way.
DOs and DON’Ts
Here are some stylistic rules for writing comments, with examples labeled Good (DO) or Avoid (DON’T).
Always support your comments with specific references
Avoid: Great navigation aids!
Good: The active site map is a great navigation tool. The fact that you can zoom out to an aerial view of the campus,
then zoom in to the right building, then the right room, then to its schematic diagram, gives maintenance personnel a
natural way to find the information they need. I was able to find the inspection records for the elevators in building 7
in less than 30 seconds.
“The main point of the comments you write is to provide
valuable feedback to entrants. Imagine that you are responding
18 a colleague who has asked for your opinion on an important
Avoid: The design is cluttered.
Good: Consider breaking the information in Figure 17 (p. 41) into four diagrams, each representing one of the major
subsystems. Then each can be on its own page, along with the legend for that subsystem. Each diagram is simpler and
less cluttered, so users can find what they're looking for more easily. Also consider applying similar simplifying
techniques to the tables on pages 46 and 48 and to the explanation of XML schemas on pages 67-84.
Write Suggestions Diplomatically
Imagine yourself presenting the comments face to face with the entrant.
Avoid: This quick reference card looks like a ransom note!
Good: You’ve organized the information clearly and logically. The large selection of fonts and colors hides that
organization. Changes to the physical appearance could help users see the structure right away. For example, consider
using a single color and typeface for the heads, and distinguishing their levels by font size and indentation.
Avoid: Whoever wrote the text of this manual should go back to second grade for a refresher course in English!
Good: Consider adding an editing pass to your production cycle to eliminate errors like the use of “it’s” for “its” and
“demonstration’s” for “demonstrations” throughout chapter 4, or the use of “descendent” for “descendant” in the chapter
on compound documents.
Note: In general, don’t bother to point out isolated errors of the above types. Only call attention to this sort of thing
if it’s such a problem throughout the entry that target users might not trust the information.
Never tell entrants what they should or shouldn’t do. Write suggestions in the imperative mode, but don’t be
Avoid: Use more white space on page 47.
“Write Suggestions Diplomatically. Imagine yourself presenting
the comments face to face with the entrant.”
Avoid: You should consider using more white space on page 47.
Good: Consider using more white space on page 47.
Avoid: You should use fewer fonts.
Good: The large selection of fonts makes the document hard to read.
For obvious points, just make them directly. Reserve the word “consider” for suggestions about issues that entrants
might approach in other ways.
Avoid: Consider including page numbers in cross-references to accommodate users who want to print from the
Good: Include page numbers in cross-references to accommodate users who want to print from the PDFs.
For points that aren’t so obvious, be a little less direct.
Avoid: Always use numbered lists in procedures.
Good: Consider using a numbered list instead of bullets for the installation steps on page 6. If you do not want to use
a numbered list for procedural steps, such as the long list of tasks on page 16, you might also consider a checkbox.
Users can print out the PDF and check off each step. Alternatively, retitle the section as Overview of Configuration
Tasks, so that readers don’t wonder why the steps lack numbers. In general, use second person when addressing
entrants, but use third person to describe entries. This is especially important in the suggestions section, where “your”
can sound accusatory.
Avoid: Your illustrations are blurry.
Good: The illustrations are blurry.
“For points that aren’t so obvious, be a little less direct.”
Use Present Tense
Write in the present tense as if you have the entry in front of you and are describing it. Use the past tense only if the
point you’re making is no longer true. For example, “Chapter 6 was confusing” (but now it’s clear). “I liked the use of
white space” (but on second thought, I hate it).
Avoid: I liked the illustrations.
Good: I like the illustrations.
When discussing a procedure you followed, however, use other tenses as appropriate.
Good: The first three links I tried took me to pages that seemed irrelevant. I then looked in the index, but I couldn’t
Write in the Active Voice
Take the time to read your sentences and recast the ones that use passive voice unnecessarily. Just as we look for
simple, direct, active prose in an entry, look for ways to express your comments simply, directly, actively.
Avoid: The manufacturing stages are clearly delineated by the use of color coding.
Good: The color coding makes the manufacturing stages stand out.
Write about Readers (Plural) to Avoid She/ He/ It Constructions
Try to avoid talking about “the reader” or “the user.” Instead, talk about readers or users, so that you don’t have to use
awkward “gender neutral” constructions.
Avoid: The informative headers help the reader find the information he or she is looking for.
Good: The informative headers help readers find the information they are looking for.
~ Richard Mateosian
“Take the time to read your sentences and recast the ones that
use passive voice unnecessarily. Just as we look for simple,
direct, active prose in an entry, look for ways to express your
comments simply, directly, actively.”
L E G A L LY B L A N D
Ar ticles? I Don’t Need No Stinking
Sometimes I wish the English language didn’t use articles. I also wish I had hot keys for
a, an, and the on my keyboard. At my previous teaching position for a hakwon (after
school academy) and my current position with a Korean company, articles were and
E lizabeth Richardson (Libby) is
currently employed as a
technical writer at Samsung
are the bane of my existence. These simple words that native speakers take for granted
seem to make up for half of my editing tasks.
Electronics Company Limited in
Suwon City, South Korea. She has Even though my position is technically as a writer, I also handle the editing for my small
a B.A. in English and an M.S. in technical writing team (three members in total), the manual team, and random
Technical Communication from
software User Interfaces (UIs). It’s a delicate balancing act to make time to do my own
the University of Missouri – Rolla.
She can be contacted at writing and edit everybody else’s at the same time to ensure we all meet our deadlines
elizabethmrichard- (especially since Koreans are famous for I-need-this-in-five-minutes assignments).
So how do I attempt to catch all of the article issues and everything else (hopefully)
Meet with the Writer
If the document is about something I’m unfamiliar with, I’ll meet with the writer before
I start looking over it. This allows the writer to give me a quick overview of the topic
and who the audience is going to be. It also gives the writer a chance to tell me
about any known issues in the document.
L E G A L LY B L A N D
Give the Document a Quick Once-over
Before I start any in depth reading or making any major changes, I’ll typically print out a copy and skim through it
looking for any glaring errors (e.g., formatting changes, figure labels, alignment issues) that I might miss if I’m editing on
the computer screen.
Read through the Document Multiple Times
I’ve found that if I try to split my attention between content, readability, grammar, etc., I usually miss something. In
order to try and prevent this, I read through the document multiple times and try to focus on a different aspect each
While reading anything, one of the things that always drives me absolutely crazy is grammatical errors. I read through
the document the first time and try to focus on only those problems. Since the writers are non-native English
speakers, this tends to become the brunt of the workload...with most of that spent in adding or removing articles.
At times that can be quite a challenge for me as well, since sometimes I’m not sure which article to use myself and
have to leave a comment for the writer asking for clarification.
The second time I read through the document, I try to focus only on the content and make sure it will be
understandable to the expected audience. Because of the Korean culture (low-context), I tend to find myself
constantly asking for more information since that’s what is expected in the Western world. We don’t like guessing.
Ambiguity and uncertainty can lead to mistakes, which in turn could lead to trouble for the company. If I could
possibly misinterpret something, the reader could as well, so I ask the author for clarification.
Also, since I work in R&D HQ, these documents are used as the basis for translation into nearly 30 languages. To
make sure we can get the clearest and best possible translation, I try to make sure only Simple English is used and all
idioms and slang have been removed.
It might seem strange that non-native speakers would use these, but Koreans are taught idioms during their English
language study from a young age. Also, oftentimes, the engineers they are working with have studied abroad and might
use slang/ idioms during the Subject Matter Expert (SME) interview.
“I’ve found that if I try to split my attention between content,
readability, grammar, etc., I usually miss something. In order to
23 and prevent this, I read through the document multiple
times and try to focus on a different aspect each time.”
L E G A L LY B L A N D
Let’s face it, editing isn’t the most thrilling thing in the world to do and can be frustrating when you find yourself
correcting the same things over and over again (“Find and Replace” in Microsoft Word works wonders for this
sometimes). I try to take breaks every hour or so, when I find myself mindlessly scrolling down the document, or
when I have to re-read paragraphs multiple times. If it’s not a very big document, I might just walk away and get a cup
of coffee, or work on something else for a bit. If it’s a large document and I have time, I might take a half a day break
from it or a few hours at least. A bored and unfocused editor doesn’t do anybody any good.
Pass it Back to the Writer
After I think I’ve caught everything, I send the document back to the writer to review my edits and make changes. I also
ask the writer to make sure to send it back to me again for another review before finalizing the document. Sometimes
this final review process can take a long time to happen. The writers tend to go back to the SMEs to clarify something
or just to drag more information out of them. Also, since the writers aren’t native speakers, sometimes we have to
meet to go over the comments I’ve made or just so I can explain why I’ve made some of the suggestions/ changes that
I tend to be a perfectionist and want my division to produce the best documentation possible, but I have to remind
myself that nobody is perfect and sometimes I can’t remember a particular rule or question changes I make. To help
combat these issues, I keep Technical Editing (Fourth Edition) by Carolyn Rude on my desk at all times.
Editing documents written by non-native speakers can be frustrating at times but also very rewarding. I like to think
that they learn something each time I pass a document back to them and that makes the “article headache” worth the
~ Elizabeth Richardson
“A bored and unfocused editor doesn’t do anybody any good.”
Document Review: The Essence of
Ever y Document
“Ink is better than the best of memory!”
Extending the thought behind this old Chinese proverb to suit the modern-day
T his article is written by
Girish Sharangpani, CEO
and founder of The Knowledge
documentation specialist, I’d say, when it comes to product documentation, it’s
extremely important for you to put ink on paper in a thoughtful manner for a long-
Labs. Girish is a proven lasting effect.
technology practitioner with
expertise in setting up IT
According to me, the key to an effective and good quality document is a thorough
incubation centers, software
development, product review process—one that verifies the accuracy of your content. You could call this
marketing, and process by different names; be it self-review, peer review, structured walk-through, or
communications. He has over whatever. A lot has been written about these processes. This article does not cover
20 years of experience;
any of these, but touches upon the basic essence of a document review process—its
predominantly in the
information technology space. importance, and the value it adds to your product and business.
As a writer, Girish has
co-authored technical and Over the last decade or so, there has been a paradigm shift in the mindset of senior
research papers on breast
cancer, has created posters management across various industrial verticals with respect to product documentation.
that were presented in More and more people have started to believe that product documentation is as
international conferences, and important as the product itself. However, even as I write this, many product
has written patents, FDA, and documents, especially those that cater to the software industry, smack of
regulatory documents. He has
a graduate degree in advance extremely poor quality in spite of the numerous quality measures adopted by
accounting and auditing from organizations.
BMCC, University of Pune, and
a postgraduate certification in
Computer Applications from
the same university.
The problem is people still do not perceive good quality product documentation as an integral part of their business.
The general notion is that documentation doesn’t add to their revenues in the long run. However, the reality is far
from it: an outstanding document can even make a mediocre product look good.
The audience of your document may differ based on the type of document you’re writing. For instance, a technical
document written for a programming audience can be different from a user guide written for an end user. Ditto for
data sheets, press releases, product brochures or catalogues, white papers, or Web pages, to name a few. Therefore,
it is crucial to give every document the precise review treatment it deserves, to have the maximum impact on your
In order to achieve this, you should select a review process with a definitive workflow.
Defining the Workflow
These days most reviewers have collaborative reviewing and editing tools at their disposal, which enable them to
perform mark up, place sticky notes, add or delete comments, and even attach other reference materials to the
original or source document. This makes the authors’ life a tad easier while editing or making corrections to that
Figure: Document Creation and Review Workflow
You can decide how you want to send the documents for review: concurrently or sequentially. There are times when
you need collaboration between reviewers. The reviewers may not have the appropriate tools to complete the review
effectively; for example, they might not have access to tools that allow markups, annotations, or routing.
26“An outstanding document can even make a mediocre product
also look good.”
You have to arrange these tools for reviewers in that case. Delivering a quality document within a specific timeline is
imperative. To achieve results, you have to include these aspects of the review process in your workflow.
Within the review process, you can also have the following aspects covered:
• Check the technical competency/ accuracy of the document
• Include useful information from test cases, exercises, and so on, in the document
• Check if all the features/ used cases are covered in the document
• Check for language review
• Making sure that the document meets “defined” standards, in terms of images, charts, templates, and the overall
Many reviews are compromised due to missing or unavailable review resources or inadequate time. To avoid such
handicaps, identify the reviewers, SMEs, engineering staff, and so on. Send the review plan to these people well in
advance. This way, they can make a note on their calendar about the review dates.
• Introduce a topic-based review process
• Adopt an Agile Development Model in the review process (if possible)
• Identify/ envisage problems, determine ahead of time who’ll provide and review corrections and inform the
reviewers when those efforts will substantiate
• Create a well thought out plan—one that optimizes the time spent by every individual, thus helping them to be as
effective and efficient as possible
• Determine the benefits of each review and make use of critical information that can improvise the review process
• Collect all the key resources: for example, SMEs, reference documents, engineering documents, standard rules
and templates, checklists (if any)
• Take the approval on the document design: an agreement in terms of what the document should contain
• Prepare (and provide) a defined process for planning and conducting reviews
“Delivering a quality document within a specific timeline is
27imperative. To achieve results, you have to include these
aspects of the review process in your workflow.”
If you plan to have an internal review cycle, then you have to make sure that the reviewers know where to look, what
to look for, time required, and so on, basically to optimize their efforts.
The ultimate goal of an optimized review process is to determine product quality and to ensure that the product is
ready for the next stage of development. These reviews depend on participation from the product development
teams. However, it is my general observation that these reviews often leave out some important information. The
reason is very simple: developers do not want to make themselves look bad by finding problems that they should have
already fixed. Hence, their participation is self-relegated to simply answering questions. It is therefore very important
that as a writer, you ask the right questions.
Publishing your technical documents to a multi-channeled world is also important. Getting your documents translated
into different languages could pose challenges at times. Probably, you will not have time to check the consistency,
correctness, and technicality of the document translated into a foreign language—especially during shorter timeframes.
There might be times when you get little review support from the development teams and almost no useful
information about prior documents or reviews. With no access to engineering documents or no transfer of
information at all, a review becomes highly improbable.
Sometimes, you simply do not have enough time to look deeply into the software. Your biggest fears might come to
life in later stages of development when too many defects are found and schedules slip due to insufficient planning,
debugging, fixing, and retesting.
To avoid such issues, you have to be on a constant vigil all the time by making sure you get all the desired information
and related documents as early as possible. Also, install the product and test its features yourself. You have to test the
product first, in order to write an effective and user-friendly document.
“It is my general observation that these reviews often leave out
some important information. The reason is very simple;
developers do not want to make themselves look bad finding
problems that they should have already fixed. Hence, their
participation is self‑relegated to simply answering questions. It
28 therefore very important that as a writer you ask the right
There are many critical factors you may have to consider while defining your document review workflow. If you are
writing different sets of documents, it is critical that you select the right reviewers. At the end of the day, the most
important criteria is not the bells and whistles the reviewers may have, but whether or not they can truly support
your efforts and deliver based on your requirements...and while doing so, provide qualitative feedback.
Over the coming years, more and more information would take the form of online documentation. With the
proliferation of online documentation, we’d have even better tools supporting the document review, enabling us to
collaborate effectively in real time. As companies strive to bring products from concept to market faster to maintain
their competitive advantage, they have to deliver good product documents by being more efficient and effective with
their review process.
~ Girish Sharangpani
“If you are writing different sets of documents, it is critical that
you select the right reviewers. At the end of the day, the most
important criteria is not the bells and whistles the reviewers
may have, but whether or not they can truly support your
29efforts and deliver based on your requirements...and while
doing so, provide qualitative feedback.”
THE MASTER SPEAKS
Designing an Effective Review
Whether you’re a writer or editor, coping with review processes is a fact of life.
Unfortunately, these processes seem to spontaneously develop over the years, with no
seeming logic behind their development. Even where a process has been carefully
T his article is written by
Geoff Hart. Geoff has
reputedly been telling tales
designed and developed, the process can gradually become atherosclerotic over the
years. At a former employer, we used a well-defined documentation review process
(sometimes ending up in that had been developed over the company’s 25-year existence, but that failed to
considerable trouble thereby) achieve timely and effective reviews simply because it had become part of the
since he was 6, but took nearly wallpaper: everybody knew it was there, but no longer “saw” it and appreciated it.
25 years to realize that he
could earn a living at this trade.
Since 1987, he’s worked for How can you develop an effective review process where none formerly existed, or
IBM, the Canadian Forest reinvigorate an existing process that desperately needs an extreme makeover? By
Service, and the Forest understanding the key tasks in any review process, and determining how the unique
Engineering Research Institute
characteristics of your situation will affect those tasks. In this article, I’ll show you how
of Canada. Since 2004, he’s
been a freelancer, and only to do this, with a very real likelihood that you’ll end up with a process that is much less
occasionally stops complaining painful for everyone.
about his boss. Geoff has
worked primarily as a technical
editor, but also does technical The essential elements of any review process are as follows:
writing and French translation. • Write and revise (self-review) the document
He claims to have survived • Perform quality control (internal review, external review, or both)
a few bouts of managing
publications groups with only a • Perform a final review
minor need for ongoing
therapy. Contact him by e-mail
at email@example.com or
THE MASTER SPEAKS
• Obtain management sign-off
• Iterate: review the review process.
Write and Revise (Self-review) the Document
The benefits of careful design are well known to professionals ranging from carpenters to engineers, and most writers
are also familiar with the concept. Yet many writers, often because of tight deadlines that lead to skipped steps, don’t
take the time to properly plan the documents they’re going to write. This is particularly true of professionals such as
engineers and scientists who are forced to write as part of their job, but who are not primarily professional writers.
In my experience, hours of time can be saved for each participant in the review process and during each step in the
review process through the simple act of planning. For writers, the obvious plan is an outline, and investing some time
to develop an outline can generate significant paybacks all by itself. The problem with outlines, of course, is that if
they’re flawed, the resulting documents will contain those flaws, and the flaws will propagate through each subsequent
phase of the review until someone spots the problem. As a result, you can generate significant return on the
investment in this planning stage by rigorously reviewing the outline before anyone begins to write. At a former
employer, several colleagues who were first and foremost researchers rather than writers had enormous difficulty
planning what they intended to say in their reports. As a result, the reports became long, poorly organized, rambling
efforts to present every thought rather than only the key points—and key points were often omitted. The result was
that at each step of the review process, from writing to final review, large amounts of time were wasted trying to
correct these problems.
I solved much of the problem by working with the author right from the start to carefully analyze the goal of the
communication and the facts that had to be presented in the document. As the editor in this workplace, the hour or
so I spent developing a strong outline saved me many more hours later in the process, generating a clear return on
investment for me because the well-designed outline drastically reduced the time required to repair a poor first draft
of the document. Others, including managers, quickly recognized the time savings this approach generated for them.
My initial success with only a few writers formed the basis for a major change to our document creation process: the
new process included a formal planning meeting during which all stakeholders (the author, the editor, the manager
responsible for the information development, and the manager responsible for final approval of the document)
rigorously reviewed the outline before the author began writing.
“In my experience, hours of time can be saved for each
31participant in the review process and during each step in the
review process through the simple act of planning.”
THE MASTER SPEAKS
As a writer, I often joke that I have a compost pile where I store my works in progress: with a little time, what starts
out as raw byproducts of the digestion process (to phrase this delicately) soon becomes valuable fertilizer. Authors
often forget to set aside this necessary time that would allow them to review their own writing with some critical
distance. Indeed, my favorite all-time review comment appeared on a document I received for editing, where the
research director’s distinctive handwriting said only one thing: “Have you read your own manuscript?” Clearly, the
author had not.
Where possible, remind authors to set aside their first draft for at least a day before returning to it and beginning to
revise it. Even a short time away from the manuscript provides the critical distance you need to revise it well.
Encourage authors, particularly those who don’t write as their primary job function, to plan to include this time in
their scheduling. There will always be plenty of other things to keep them busy until they can return to the
Perform Quality Control: Internal Review
All publishers who care about the reactions of their readers insist on some form of quality control before they release
a document for public inspection; this is generally referred to as an internal review, as distinct from the external review
discussed in the next section. The internal review usually takes the form of editing in organizations that recognize the
importance of well-edited writing, or of peer review in organizations that are less serious about quality or lack the
budget for an editor. This step should never be eliminated, since it’s the only way to catch and fix obvious problems
before others encounter them. If your organization’s reputation is an important asset, this phase cannot be skipped.
Internal review takes two forms. The first, which is present in all organizations, is a straightforward technical review.
The goal of this review is to catch significant errors of fact or logic that would prevent the safe or successful use of a
product or that would prevent or interfere with understanding of information. This review should also identify
problems that make it unnecessarily difficult to understand the writing, but that is often a secondary goal. These
problems lead to the second form of internal review, namely an editorial or peer review. Here, the goal is to take a
technically correct document and make it more readable. This second review is less well appreciated, and many
organizations have no professional editor to do this work; in that case, the writers may perform peer review of their
own work, or the original writer may review and improve their own work based solely on the feedback obtained
during the technical review.
“Where possible, remind authors to set aside their first draft
for at least a day before returning to it and beginning to revise
it. Even a short time away from the manuscript provides the
critical distance you need to revise it well. Encourage authors,
particularly those who don’t write as their primary job function,
to plan to include this time in their scheduling. There will
32always be plenty of other things to keep them busy until they
can return to the manuscript.”
THE MASTER SPEAKS
Over the years, I’ve found that performing an editorial review before the technical review offers a large payback. In
the absence of such a review, technical reviewers often spend far more time correcting grammar, punctuation,
formatting, and other aspects of the writing than they spend focusing on the content. In contrast, providing a well-
edited document for review removes all these obstacles to reading, allowing the technical reviewer to focus on the
content—which is, after all, their area of expertise. Performing the editorial review first will not entirely eliminate
comments related to the quality of the writing, but it will allow reviewers to focus more of their attention on the
technical aspects than if their concentration is constantly being interrupted to correct typos. This approach increases
both the effectiveness of the review (more technical errors are caught and fixed) and the speed of the review (less
time is wasted fixing minor errors), and thus generates an obvious return on investment for the editor’s time.
Quality Control: External Review
A well-done internal review can catch both major and minor problems, and can create a greatly improved product,
but it has one large failing: the people who perform the internal review are highly familiar with the subject they’re
writing about, and thus, may not be representative of the typical reader, who will be far less familiar with the specific
information. Moreover, organizations gradually tend to develop a set of standard operating assumptions that become
part of their subconscious thought process and that subsequently bias how they communicate about a topic. Even
experienced editors, who are experts in finding and resolving the problems that arise from assumptions and implicit
understandings, are vulnerable to this kind of problem, particularly after many years spent absorbing an organization’s
standard practices and assumptions. The fresh set of eyes provided by an outsider external to the organization solves
both problems: the reader’s naiveté reveals any problems that result from the implicit assumptions made by the
insiders who created the document.
External review is an essential part of some publishing processes, particularly in the sciences. For example, it’s not
possible to publish scientific research papers in most journals before the manuscript has been exhaustively and often
ruthlessly critiqued by experts in the field. In other fields, reports being written for people who have the authority to
reject a report or the activity based on the report (e.g., government regulators), and these people can be enlisted as
reviewers to ensure that the final report will be acceptable. In the absence of this review, a lucrative contract may not
be awarded or a key project may be stalled. In still other cases, external review is a luxury rather than a necessity: the
value of the review is recognized, but because of time constraints or other problems, the review is not performed.
“A well-done internal review can catch both major and minor
problems, and can create a greatly improved product, but it
has one large failing: the people who perform the internal
review are highly familiar with the subject they’re writing
about, and thus, may not be representative of the typical
33reader, who will be far less familiar with the specific
THE MASTER SPEAKS
As a result of these concerns, a documentation manager or editor should advocate strongly to include some form of
external review in the overall review process. To succeed, you must first understand the reasons why these reviews
are not being performed. If the key issue is time, then careful planning (scheduling plus project management to track
progress towards deadlines) may free up the time required to permit an external review. If the key issue is political,
then understanding the politics behind how the organization makes decisions can provide insights into solutions; in
one case, the obstacle was embarrassment over the quality of the materials being sent for external review, and the
solution was to edit the materials beforehand. And if the issue is nothing more than apathy, sometimes it’s possible to
arrange an external review on your own authority, without asking for permission. It’s often the case that managers
who won’t formalize the process of external review happily accept the improved quality that results from such
reviews—provided that the review process doesn’t interfere with meeting their own deadlines or lead to any
problems that require their attention.
Perform a Final Review
Whether you conduct rigorous internal and external reviews, or only perform some cursory quality control, at least
one final review stage is necessary. Since it’s inevitable that some changes will have been made as a result of early
reviews, someone must ensure that the author has responded correctly to the review suggestions. Although this can
be delegated to the author, my experience has shown that left to their own devices, authors often respond
inappropriately, misunderstand review suggestions, or introduce new errors while responding to the reviews. In nearly
20 years of working as an editor, I’ve only rarely found an author with a perfect record; some simply ignore comments
they disagree with or misunderstand, and most introduce additional errors even when they respond appropriately.
(It’s human nature to grow bored with a document after revising it for the tenth time, and that boredom weakens the
author’s focus and inevitably leads to errors.)
As a result, the ideal review process includes a final editorial review. This lets you polish the document to a fine glow
and produce the maximum possible quality. But at a minimum, this final review gives you one last chance to spot any
problems that have made it through all previous stages of the review process. These problems are legion, and cannot
simply be assumed to have been fixed; examples include orphaned phrases such as “graphic artist: please replace this
figure with a new one” and authors who, knowing that there would be no final review, took the opportunity to slip
scurrilous or offensive statements into their manuscript.
“In nearly 20 years of working as an editor, I’ve only rarely
found an author with a perfect record; some simply ignore
comments they disagree with or misunderstand, and most
introduce additional errors even when they respond
appropriately. (It’s human nature to grow bored with a
document after revising it for the tenth time, and that
34boredom weakens the author’s focus and inevitably leads to
THE MASTER SPEAKS
You can understand this part of the process by comparing it with a product assembly line: before a product is boxed
and shipped to the consumer, someone always tests it to ensure that it’s working right. For computers, this may
involve a 24-hour “burn-in”, with the product turned on for this long to ensure that it won’t burn out as soon as it’s
plugged in, supplemented by a suite of software tests that rigorously and automatically test all key features of the
installed software; for automobiles, it may involve a test drive from the end of the assembly line to the vehicle
transporter that will take the car to a dealer.
In traditional print publishing, this final review occurred after layout of the document and was referred to as
proofreading (i.e., reading the document as proof that the final results were correct). With modern all-electronic
production processes, and particularly with online publishing (e.g., help systems and Web sites), there’s a pernicious
assumption that if you’ve carefully controlled the process up to this point, there will be no additional errors to find.
I’ve found few editors who believe this to be the case. Indeed, when a former employer suggested doing away with
this aspect of the publishing process, I spent a few months documenting (and fixing) the errors that resulted. Despite
careful control of quality during the internal and external reviews, and an experienced and skilled desktop publisher, I
routinely found dozens of small errors and often more than one significant error that would not have been caught
without a final proofreading.
Obtain Management Sign-off
The final step in any publishing process is some form of management signoff. Depending on the nature of the
organization and of the people involved, this step may be a simple “rubber stamp” exercise; in other cases, the
manager who will be responsible for the consequences of publishing the document will rigorously examine the
document down to the level of individual punctuation. In either case, all the quality control you’ve performed thus far
in the process will be justified: if there are no errors for the manager to detect, they will gradually come to trust you,
and will spend less time focusing on the minutiae. This makes better use of a manager’s expensive time, avoids costly
delays at the end of the publication process, and builds a sense of trust and cooperation.
The planning meeting I described earlier in this article is a key success factor. If the manager has carefully reviewed the
documentation plan right at the start, this greatly decreases the risk of finding the results unacceptable at the end of
the process. In particular, the manager has less incentive to justify their participation in the review process by insisting
on major last-minute changes because they have already insisted on these changes at the start of the process.
“If the manager has carefully reviewed the documentation
35plan right at the start, this greatly decreases the risk of finding
the results unacceptable at the end of the process.”
THE MASTER SPEAKS
It’s certainly true that sudden insights at the last possible moment can lead to extensive changes in the documentation,
and this is one justification for a final management signoff. But more often, the approval task is simple and fast for a
document that has survived all the previous steps in the review, and provides yet another example of how building
quality and consensus into the initial stages of documentation development pays off with time savings and increased
quality later in the process.
For products such as software that are evolving continuously, the writing and review process will be repeated
(iteration) for the lifetime of the product—as often as twice per year for decades with modern software. For other
situations, documents may be revised only occasionally, often after a long delay; this is the case with dictionaries and
technical specifications, for example. Iterative review is often seen as a necessary evil, but in truth, it should be seen as
a final reality check on your process. Reader reviews of your information between versions provide key insights into
what you’re doing right—and perhaps more importantly, into what you’re doing wrong. Developing a mechanism for
such reviews permits continuous improvement of the quality of the materials you produce, particularly if you can
address those reviews in the down-time between releases of the document.
Reader feedback can be difficult to obtain, particularly where you don’t have direct access to these readers. But there
are always ways to find out whether the material you’ve produced is meeting expectations. Review articles in the
popular press or in specialty magazines are a great source of information, whether you’re producing software or best-
selling popular science books. Best-selling third-party books such as the Pogue Press/O’Reilly “missing manuals” often
provide keen insights into more effective ways to communicate or things that you’ve missed in your own
documentation. If you lacked the time or resources to have your materials professionally edited, why not hire an
editor during the down-time before the next writing and review cycle begins? Use the insights provided by that
professional to do a better job in your next iteration of the writing. Look for online communities who discuss what
you’ve written to see what they’re saying, and ask leading questions to generate discussions about where you’ve
succeeded and where you’ve failed.
Last but not least, talk to your colleagues in technical support and training. They deal directly with the people who use
the information you create, and can provide important insights into where that information fails to meet reader needs.
“If you lacked the time or resources to have your materials
professionally edited, why not hire an editor during the
down-time before the next writing and review cycle begins?
Use the insights provided by that professional to do a better
job in your next iteration of the writing. Look for online
communities who discuss what you’ve written to see what
they’re saying, and ask leading questions to generate
36discussions about where you’ve succeeded and where you’ve
THE MASTER SPEAKS
Iterate: Review the Review Process
This article neglects many important issues that arise from the details of this process. Among other things, each
company and context will have certain unique characteristics that change how you look at the review process. For
example, sometimes it’s possible to conduct simultaneous reviews of a document to greatly reduce the time
compared with sequential reviews. This raises the issues of how to reconcile conflicting review comments and how to
obtain the synergies that are possible when reviewers can interact and conduct dialogues as they simultaneously
review a document. Tools such as wikis (see, for example, http://wiki.org/) and blogs (e.g., http://
www.livejournal.com/) allow readers and publishers to interactively create and update information, and exciting new
tools such as XMetal Reviewer (http://www.xmetal.com/en_us/products/xmetal_reviewer/index.x) will increasingly
solve this problem.
In addition, as I noted at the start of this article, review processes eventually fossilize with the passage of time, and
what was once a powerful living organism transforms into a burdensome chunk of stone. Periodically, the stakeholders
involved in any review process should take the time to confirm that it is still serving its intended purpose, and that
people are still following the process. An organization’s context may have changed, requiring the addition of new
review steps (e.g., by the organization’s lawyer, to confirm compliance with new regulations) or the removal of old
steps (e.g., no more management approval if they trust you to do the job right). Technological change may also let you
improve your process. Even if no changes are necessary, the dialogue between stakeholders that results from this
review process is itself valuable because it keeps the lines of communication open and instills a sense of teamwork that
is often lacking.
My goal in writing this article is not to suggest that reviews are easy, but rather to explain the goals and constraints of
the key components of a review process. In so doing, I’ve illustrated how to take advantage of each phase of review,
while minimizing its constraints. As my examples have shown, you can obtain remarkable payback from investing the
time to understand the process and to look for ways to make it work better. I encourage you to explore some of the
ideas I’ve presented, and to report your results to readers of this magazine. I look forward to your insights!
This article has been reprinted with permission from the author. Previously published as: Hart, G. 2006. Designing an effective
review process. Intercom July/August 2006:18–21.
~ Geoff Hart
“Review processes eventually fossilize with the passage of
37time, and what was once a powerful living organism
transforms into a burdensome chunk of stone.”
S P O T L I G H T — PA RT I
Inter view with Shivabalan S
1. Tell us something about your education. Did you study to become a
I am a BA English graduate. I did not study to become a technical writer, but more
S hivabalan has been a part of
the tech comm industry for
close to 12 years now. His
to get into Journalism.
documentation expertise includes 2. When did you realize you were a writer at heart?
writing User Guides, Help
Systems, and Release Notes. He I realized this during my first work stint. I was asked to write a White Paper on
has a strong multicultural
one of the products we were working on. Though it looked like there wouldn’t be
background, having worked in
Malaysia, the United States, India, even a page worth of content, I actually ended up writing five pages of relevant
and Indonesia. He is currently content. This experience made me look out for specialized roles in writing.
managing a team of
personnel at Dell India R&D. 3. How did you secure your first gig as a technical communicator?
You can contact him at
Shivabalan_S@dell.com. It was a challenge; I failed more than three interviews initially, given the lack of
experience. I then took about a week to prepare from my failed experience, by
brushing up my English language skills, looking up existing manuals, and
understanding the basics of documentation life cycle. This preparation helped me
in securing my first writing job.
S P O T L I G H T — PA RT I
4. What challenges did you face as a technical communicator?
Pretty much the same as most other technical communicators; lack of access to the product I was documenting,
incomplete design documents, not enough time with developers and testers to give me interviews, ever-changing
schedules, and interestingly, lack of processes in a couple of companies.
5. What efforts did you make to overcome these obstacles?
I worked with engineering managers for getting access to prototypes, to an extent that solved the problem of
understanding the product features and its workflow. After that, I tracked incremental changes to the product
features by using a spreadsheet. This way I didn’t miss documenting any feature.
As for technical interviews, I worked with the developers to give me time. And after they committed, I put them
on their calendars, copying their managers. This also, to an extent, helped me get time with them to answer my
questions and review my drafts.
Companies where there were no processes were companies where there were no dedicated writing teams as
well. I relied heavily on the Project Managers to set up ad hoc processes. I created documentation plans, covering
the documentation deliverables, schedules, risks, and their mitigation plans, and shared the plan with the team.
The documentation plan helped set up an interim documentation process for me.
6. Tell us about your work experience. List the companies you have worked with to date.
I have now close to twelve years of technical writing experience, with work assignments in India, the United
States, Malaysia, and Indonesia. I have worked with Eastern Software Systems, Global Software Technologies,
HTC Software Development Center, Satyam, Oracle, and now, Dell India R&D.
7. How is it working as a Documentation Manager at Dell India R&D? Describe a typical day at work
Working as a Documentation Manager at Dell India R&D is full of challenges, yet enjoyable. The challenge lies in
not only managing people, but projects as well. As you know, Dell is a product company; so we have multiple
“Working as a Documentation Manager at Dell India R&D is
full of challenges, yet enjoyable.”
S P O T L I G H T — PA RT I
releases going almost every month. And it is a huge challenge to provide documentation for each of their
products. Our schedules are set on stone, so we do not get any leeway for slipping dates. It requires constant
juggling to make sure that the documentation sets keep hitting the right dates.
And that pretty much describes a typical day at work for me; keeping an eye on all projects, tracking team
members’ achievements, their strengths and development opportunities, and mentoring them when required.
8. Describe the differences between writing and managing. What skill sets are required to succeed in
each of these profiles?
The ability to communicate (written as well as spoken) easily using the English language, the ability to understand
business context (about why the project or product is being developed), and the ability to lucidly explain key
features and workflow to end users, are the primary skills required for a technical writer to succeed.
Managing people is a different ballgame altogether. One has to coach novices, keep track of their performance,
resolve conflicts within the team, and be able to see the big picture and strategize accordingly.
9. What similarities or differences did you find in working for a product company (Oracle) and
working for a service company (Satyam)?
I can only comment on the differences, not the similarities (except that schedules were followed aggressively in
both the setups.)
Product companies usually have well–defined documentation processes and teams, because their products are
accompanied with supporting documentation. Writers working for such companies are exposed to both
templates and style guides.
On the other hand, service companies ask for documentation only if their clients require it. Such companies
depend more on ad hoc processes, or worse, no processes! So, it is that much more a challenge to get a
developer’s time, to get access to completed design documents, and to come up with templates.
“The ability to communicate (written as well as spoken) easily
using the English language, the ability to understand business
context (about why the project or product is being developed),
and the ability to lucidly explain key features and workflow to
40 users, are the primary skills required for a technical writer
S P O T L I G H T — PA RT I
But I believe most service companies have now started recognizing the importance of documentation and are
providing equal importance to it.
10. Have you ever presented at a technical writing learning session or an annual conference?
11. Tell us something about your accomplishments as a technical communicator.
I have been able to succeed as a writer largely because I think like an end user before I begin to write. This helps
me write about what is most required in a product, clearly and concisely.
A couple of tangible accomplishments are a company award and an STC award for two different deliverables.
12. What suggestions do you have for technical communicators who wish to move into management?
There are two management paths: project management and people management. For project management, technical
writers must be very good at time management. They should also be able to juggle with multiple deliverables at
the same time (this is especially critical in a product company). They should be good and regular in
communication with various stakeholders to be on top of project requirements and schedules.
To move into people management, technical writers must have good rapport with their team members. They
should be creative, be able to think out of the box, and be able to see the big picture. They should also be able to
align their team members’ goals with the organization goals to create a win-win situation for all.
13. Who are your favorite bloggers and why?
I am not into blogging, yet.
“To move into people management, technical writers must
have good rapport with their team members. They should be
creative, be able to think out of the box, and be able to see
the big picture. They should also be able to align their team
41members’ goals with the organization goals to create a
win-win situation for all.”