1

FROM THE EDITOR ’S DESK (GUEST POST )

S tay ing Sane w i th San i t y Check 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

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

common than is necessary, and I say it doesn’t have to be that way. It does need to be

managed, however. I’m going to explore the Sanity Checks as a way of filtering out the

unseen errors, even after the review cycles are complete. I will do so in form of some

most likely questions.

• We are a team of several writers, developers, and QA engineers with a

solid review process. Aren’t sanity checks just a big overhead for me?

No, they are not. Your review cycles will take care of typos, grammar, missing

content, and inaccurate technical details. However, sanity checks catch errors that,

as a writer, are your responsibility. They ensure certain things that are not part of

any reviews, don’t fall through the cracks. I will address these in the next question,

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.

Apr i l 2 0 09 Documen t Rev i ew Spec ia l I s sue Vo lume 41

From the Ed i to r ’ s de sk : 1-3

In Focus : 4-7 Too l s : 8-13

D i rec t i ons : 14-16 Re f l ec t i ons : 17-21

L eg a l l y B land : 22-24 Con fe ss ions : 25-29

T he M as te r Sp eaks : 30-37

Spo t l igh t : 38-42 , 43-47

Wr i t e r o f the Month : 48

S umedh is a senior technical writer and trainer. His

company, CrackerJack WordSmiths, offers technical writing and training services to clients in India, Canada and the United States. During his career, he has worked in Europe, Australia, India, Singapore, and the United States. He has recently relocated to Toronto, Canada. He has a rich experience of nearly 15 years in all aspects of documentation life cycle from design to implementation in software and high-tech environment. He can be contacted at sumedh.techwriter@gmail.com.

2

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

FROM THE EDITOR ’S DESK

“There is no single formula for a successful sanity check. Every writer in your team should prepare his/ her own sanity checklist.”

Tip:

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.

3

• 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,

indeed.

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

FROM THE EDITOR ’S DESK

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

4

IN FOCUS

“Mak ing a Mark” a s a Techn ica l Ed i t o r o r Rev i ewe r 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

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

deliverables in documentation, and second, the recognition of reviewing and editing as

a competency that is developed and enhanced over a period of time.

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 maturity and competency, and also a position of immense responsibility.

Contrary to popular myth, editing is not only about marking corrections, or

faultfinding; it is about total involvement in a documentation assignment, including

planning, collaborating, and defining best practices.

The responsibilities of a technical editor include:

Planning

• Understanding the aim and audience of a documentation assignment

T his article is written by Aneesha Myles Shewani, a

Lead - Technical Editor with Fiserv, Noida, India. She has a rich experience of nearly 9 years, having started her career with content writing for Times Internet Limited, and then moving into technical documentation for organizations like Infogain and Computer Sciences Corporation. She has worked primarily in the domain of insurance and risk management, and payment and industry products. Apart from being extremely passionate about technical writing and editing, as a profession and an art, she also has a penchant for creative writing and regularly maintains 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 writing fiction.

5

• 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)

Collaborating

• 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

Writing

• Restructuring content, making it more readable and organized

• Writing for some specific sections like overview, or samples for the team to follow

Editing

• Undertaking editing tasks, such as checking grammar, general word usage, spelling, and language-based edits

Reviewing

• 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

Analyzing

• Preparing a best practices document based on the defect logs

• Analyzing defect logs and preparing strategies for reducing defects and improving the document quality

IN FOCUS

“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 maturity and competency, and also a position of immense responsibility.”

6

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.

IN FOCUS

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

7

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

documentation team!

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

IN FOCUS

“The better your track record as a technical writer, the better your chances of becoming the technical editor or reviewer for a documentation team!”

8

TOOLS

An In t roduc t i on to D ITA Brief History

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

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.

In March 2004, IBM donated DITA to OASIS (Organization for the Advancement of

Structured Information Standards), where it is now managed by the OASIS DITA

Technical Committee. In April 2005, OASIS approved Version 1.0 of the DITA

specification.

Overview

The name “DITA” has been derived as follows:

• Darwin: Named after Charles Darwin because the topics in DITA can be

specialized to inherit properties of the basic topics.

• Information Typing: DITA was designed for technical information based on

information architecture of Concept, Task, and Reference.

• Architecture: DITA is a model for extension of both design and processes.

S hashi Prabha studied to become an Electronics and

Communication engineer, but luck had better plans in store for her. She has a Bachelor of Technology degree from N. I. T. (formerly known as R. E. C.), Surathkal. After graduating, Shashi decided to expand her skills and knowledge by working as a faculty member at Aptech, Chennai. Later, she worked as a technical support executive at CLi3L e-services Limited, Bangalore. She built upon her experience by 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 telecommunication products. Her primary interest lies in API documentation.

9

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:

1. Task

2. Concept

3. Reference

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

TOOLS

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

<task>

<title>

<shortdesc>

<prolog>

<taskbody>

<prereq>

<context>

<steps>

<example>

<postreq>

<result>

<related-links>

10

The structure of a concept topic is as follows:

• 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

follows:

TOOLS

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

<concept>

<title>

<shortdesc>

<prolog>

<conbody>

<section> | <example>

<related-links>

<task>

<title>

<shortdesc>

<prolog>

<taskbody>

<prereq>

<context>

<steps>

<example>

<postreq>

<result>

<related-links>

11

DITA Maps

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.

TOOLS

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

<map> <topichead>

<topicref>

<reltable>

<anchor>

<navref>

<topicgroup>

<topicmeta>

12

Key Features

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

cost.

• 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:

− PDF

− XHTML

− 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

publishing workflows.

TOOLS

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

13

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.

References:

• http://www.ditausers.org/

• http://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture

• http://www.ibm.com/developerworks/xml/library/x-dita6/

~ Shashi Prabha

TOOLS

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

14

DIRECTIONS

A Bug ’ s L i f e : How to Make Your Ed i t o r ’ s L i f e—and Your s—Simp le r What the heck are you talking about?

Yes, this article is inspired by the animation movie with the same title.

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

deviate, a supervisor (editor) beats you back to the line (conform to standards).

Thankless Job

For most people, an editor’s is a thankless job. You get credit for good writing, but an

editor gets brickbats if something goes wrong. He/ she is doing his/ her job, that is, to

identify and point out your (writer’s) errors. He uses editorial markups, and to make

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.

Be Professional

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.

T his article is written by Sridhar Machani, a

technical communicator at Siemens PLM Software, Pune, India. He is part of the editorial team of INDUS, STC India Chapter’s newsletter. Sridhar is also an active blogger. He maintains a popular blog on technical communication. You can read his blog posts here.

15

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

need.

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.

Set Expectations

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

work.

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.

Self-review

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

DIRECTIONS

“Contest and argue with the markups, not the person. Be humble and accept your mistakes.”

16

A Simple, Happy Life

~ Sridhar Machani

DIRECTIONS

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

17

REFLECTIONS

How to Eva lua t e En t r i e s 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

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.

With the audience hat firmly on your head, decide what the entry ought to accomplish.

Ask yourself what information it should contain, what navigation it should provide,

what it can assume and what it should explain, and so forth. The answers to these

questions become the basic framework within which you view the entry. Base your

evaluation on how well the entry communicates within that framework.

Having established a judging framework in this way, you can look at the STC criteria

for entries of this type to help focus your attention on details, but always remember

that the big picture is more important than details. Your objectives in evaluating the

entry are:

• Recognize and provide positive feedback for the ways in which the entry succeeds

in meeting the objectives you set for it.

• Identify, and spell out ways to improve, areas in which the entry falls short

of the objectives you set for it.

R ichard Mateosian began his career as a

mathematician. He earned a PhD in math from UC Berkeley in 1969. Starting while he was still in graduate school, he spent about fifteen years as a programmer and systems development manager. In 1979 Richard wrote Programming the Z8000, which launched him into ten years as a technical marketer for high-end microprocessors. Since the early 1990s, Richard has worked exclusively as a technical communicator. He specializes in writing for an audience of programmers. He is active in STC, where he has been part of the Berkeley Chapter leadership for many years. He has also been active in the Northern California regional technical communication competitions.

18

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.

General Approach

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.

Avoid Humor

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.

REFLECTIONS

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

19

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

dogmatic.

Avoid: Use more white space on page 47.

REFLECTIONS

“Write Suggestions Diplomatically. Imagine yourself presenting

the comments face to face with the entrant.”

20

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

PDFs.

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.

REFLECTIONS

“For points that aren’t so obvious, be a little less direct.”

21

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

find “widgetation.”

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

REFLECTIONS

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

22

LEGALLY BLAND

Ar t i c l e s ? I Don ’ t Need No S t ink ing A r t i c l e s ! 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

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.

Even though my position is technically as a writer, I also handle the editing for my small

technical writing team (three members in total), the manual team, and random

software User Interfaces (UIs). It’s a delicate balancing act to make time to do my own

writing and edit everybody else’s at the same time to ensure we all meet our deadlines

(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)

quickly?

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.

E lizabeth Richardson (Libby) is currently employed as a

technical writer at Samsung Electronics Company Limited in Suwon City, South Korea. She has a B.A. in English and an M.S. in Technical Communication from the University of Missouri – Rolla. She can be contacted at elizabethmrichard-son@gmail.com.

23

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

time.

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.

LEGALLY BLAND

“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 time.”

24

Take Breaks

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’ve made.

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

pain.

~ Elizabeth Richardson

LEGALLY BLAND

“A bored and unfocused editor doesn’t do anybody any good.”

25

CONFESS IONS

Document Rev i ew : The E s s ence o f Eve r y Document

“Ink is better than the best of memory!”

Extending the thought behind this old Chinese proverb to suit the modern-day

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-

lasting effect.

According to me, the key to an effective and good quality document is a thorough

review process—one that verifies the accuracy of your content. You could call this

process by different names; be it self-review, peer review, structured walk-through, or

whatever. A lot has been written about these processes. This article does not cover

any of these, but touches upon the basic essence of a document review process—its

importance, and the value it adds to your product and business.

Over the last decade or so, there has been a paradigm shift in the mindset of senior

management across various industrial verticals with respect to product documentation.

More and more people have started to believe that product documentation is as

important as the product itself. However, even as I write this, many product

documents, especially those that cater to the software industry, smack of

extremely poor quality in spite of the numerous quality measures adopted by

organizations.

T his article is written by Girish Sharangpani, CEO

and founder of The Knowledge Labs. Girish is a proven technology practitioner with expertise in setting up IT incubation centers, software development, product marketing, and communications. He has over 20 years of experience; predominantly in the information technology space. As a writer, Girish has co-authored technical and research papers on breast cancer, has created posters that were presented in international conferences, and has written patents, FDA, and regulatory documents. He has a graduate degree in advance accounting and auditing from BMCC, University of Pune, and a postgraduate certification in Computer Applications from the same university.

26

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

audience.

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

document.

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.

CONFESS IONS

“An outstanding document can even make a mediocre product also look good.”

27

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

design element

Best Practices

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

itself

• 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

CONFESS IONS

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

28

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.

Problem Areas

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.

CONFESS IONS

“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 is therefore very important that as a writer you ask the right questions.”

29

Conclusion

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

CONFESS IONS

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

30

THE MASTER SPEAKS

De s ign ing an E f f e c t i ve Rev i ew P roce s s 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

designed and developed, the process can gradually become atherosclerotic over the

years. At a former employer, we used a well-defined documentation review process

that had been developed over the company’s 25-year existence, but that failed to

achieve timely and effective reviews simply because it had become part of the

wallpaper: everybody knew it was there, but no longer “saw” it and appreciated it.

How can you develop an effective review process where none formerly existed, or

reinvigorate an existing process that desperately needs an extreme makeover? By

understanding the key tasks in any review process, and determining how the unique

characteristics of your situation will affect those tasks. In this article, I’ll show you how

to do this, with a very real likelihood that you’ll end up with a process that is much less

painful for everyone.

The essential elements of any review process are as follows:

• Write and revise (self-review) the document

• Perform quality control (internal review, external review, or both)

• Perform a final review

T his article is written by Geoff Hart. Geoff has

reputedly been telling tales (sometimes ending up in considerable trouble thereby) since he was 6, but took nearly 25 years to realize that he could earn a living at this trade. Since 1987, he’s worked for IBM, the Canadian Forest Service, and the Forest Engineering Research Institute of Canada. Since 2004, he’s been a freelancer, and only occasionally stops complaining about his boss. Geoff has worked primarily as a technical editor, but also does technical writing and French translation. He claims to have survived a few bouts of managing publications groups with only a minor need for ongoing therapy. Contact him by e-mail at ghart@videotron.ca or geoffhart@mac.com

31

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

THE MASTER SPEAKS

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

32

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

manuscript.

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.

THE MASTER SPEAKS

“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 manuscript.”

33

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.

THE MASTER SPEAKS

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

34

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.

THE MASTER SPEAKS

“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.)”

35

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.

THE MASTER SPEAKS

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

36

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.

THE MASTER SPEAKS

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

37

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!

~ Geoff Hart

THE MASTER SPEAKS

“Review processes eventually fossilize with the passage of time, and what was once a powerful living organism transforms into a burdensome chunk of stone.”

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.

38

SPOTLIGHT—PART I

In t e r v i ew w i th Sh i vaba lan S 1. Tell us something about your education. Did you study to become a

writer?

I am a BA English graduate. I did not study to become a technical writer, but more

to get into Journalism.

2. When did you realize you were a writer at heart?

I realized this during my first work stint. I was asked to write a White Paper on

one of the products we were working on. Though it looked like there wouldn’t be

even a page worth of content, I actually ended up writing five pages of relevant

content. This experience made me look out for specialized roles in writing.

3. How did you secure your first gig as a technical communicator?

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 hivabalan has been a part of the tech comm industry for

close to 12 years now. His documentation expertise includes writing User Guides, Help Systems, and Release Notes. He has a strong multicultural background, having worked in Malaysia, the United States, India, and Indonesia. He is currently managing a team of documentation support personnel at Dell India R&D. You can contact him at Shivabalan_S@dell.com.

39

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

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

SPOTLIGHT—PART I

“Working as a Documentation Manager at Dell India R&D is full of challenges, yet enjoyable.”

40

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.

SPOTLIGHT—PART I

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

41

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?

No.

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.

SPOTLIGHT—PART I

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

42

14. Have you interacted with technical communicators from a different geographical location? If yes, how has your experience been like?

Yes, I have mostly interacted with writers in the United States. I have only learnt from my interactions with them.

What I like most is their ability to convey messages effectively using least number of words.

15. Who are your favorite authors?

My favorite authors are Somerset Maugham, RK Narayan, and PG Wodehouse. They are masters of the English

language and I admire the way they present even simple situations beautifully.

16. Finally, any words of wisdom for fledgling technical communicators.

Only two. First, look up some good manuals on the Web and see how they are structured. Finally, analyze how

the content is laid out before entering the field.

While writing, think like your end user and play with the product as much as possible; this will greatly help you in

fully understanding the product while coming up with relevant content.

~ This interview was conducted by Rahul Prabhakar

SPOTLIGHT—PART I

“While writing, think like your end user and play with the product as much as possible; this will greatly help you in fully understanding the product while coming up with relevant content.”

43

SPOTLIGHT—PART I I

In t e r v i ew w i th Samee r Chhabra 1. Tell us something about your education. Did you study to become a

writer?

I am a Commerce graduate, who also studied Science with Biology in high school,

and scored the highest in Geography in middle school. My education has been

spread over the country—starting from Punjab, to Gujarat, then UP, and Delhi. I

did not go through any formal courses for writing, but learnt everything on the job

and mainly through in-house trainings.

2. When did you realize you were a writer at heart?

After I started to write stuff other than what was required at work.

3. How did you secure your first gig as a technical communicator?

It was sometime in 1999. I was already a Microsoft Certified Systems Engineer

working with an Internet Service Provider, but still trying to wrap up my last

semester at NIIT. I saw a poster at the NIIT center, asking people who knew

English, to apply for a job as an instructional designer with NIIT. It was the first

time I heard about this profession. I enquired a little more and figured out that

the job required writing about technology and technical subjects. It was a

great opportunity for me.

S ameer Chhabra is an experienced technical

communicator, who has been working in the IT industry for more than 11 years. He started his career as a faculty member at the NIIT Ludhiana Center and presently works as a Program Manager at Microsoft Global Ser-vices India (MGSI) in Hyderabad. Sameer has a rich experience in program management, project management, and people management, in addition to technical editing, technical writing, and instructional design. He is a Microsoft Certified Systems Engineer (MCSE) and a member of the Society for Technical Communication (STC) India chapter. He can be reached at sameer.chhabra@live.com.

44

I thought, “They’re only asking for English, but I also bring along an understanding of technology. Good for me!” That is

how I got started with my technical communicator career.

4. What challenges did you face as a technical communicator?

When I started to work as a technical communicator, everything around me was a challenge. The biggest

challenge I think was that I didn’t know much about this profession. During my first interview for a technical

communicator’s job, I told the interviewer, in as many words, that I was clueless about instruction design. Not

many people knew about this profession at that time, and even employers looked for people with a basic aptitude

and the right attitude.

Since then, there have been many other types of challenges such as understanding the audience, appreciating

customer feedback, taking ownership for what you write, and making others realize that technical communication

brings value to an organization.

5. What efforts did you make to overcome these obstacles?

I treated every challenge as an opportunity to learn. I learnt from every experience—with every paragraph I

wrote and with every project I completed. This profession requires you to learn continuously and at all times. It

does not mean that you’ll become a subject matter expert in everything that you do or in every subject that you

write about. It is more about your attitude. Take every challenge as an opportunity to learn, perform, and grow.

6. Tell us about your work experience. List the companies you have worked with to date.

I have a total working experience of more than 11 years in the IT industry, with companies small and big. These

include NIIT, Global Electronic Commerce Services (part of GTL Limited), Compunnel, SDI Technologies (now

Soltius Infotech), Oracle, and Microsoft.

7. How is it working as a Program Manager at Microsoft Global Services India? Describe a typical day at work for you.

SPOTLIGHT—PART I I

“I treated every challenge as an opportunity to learn. I learnt from every experience—with every paragraph I wrote and with every project I completed. This profession requires you to learn continuously and at all times. It does not mean that you’ll become a subject matter expert in everything that you do or in every subject that you write about. It is more about your attitude. Take every challenge as an opportunity to learn, perform, and grow.”

45

I joined Microsoft Global Services India (MGSI) in its first year of existence. Since then I’ve spent three years here,

with different roles, responsibilities, and job titles. In my present role as a program manager, I am responsible for

evangelizing and leading the technical communication initiative at MGSI.

A typical day for me entails working with different engagement teams within MGSI, providing them with content

project management and technical editing support. In addition, I also help the company in hiring and managing

technical writing resources for these teams.

8. Describe the differences between writing and managing. What skill sets are required to succeed as a writer and a manager? Also, what similarities or differences did you find in working for product companies like Oracle and Microsoft and working for a service company like NIIT?

MGSI is actually part of the Microsoft Services organization, providing global delivery support to the consulting

divisions of Microsoft across the world. So, to answer your question, all I can say is that I have worked with a

product company like Oracle, a pure services company like NIIT, and the services arm of a product company like

Microsoft. They are different in their own ways and provide their own unique experiences. As a technical

communicator, your role might not change a lot, but what changes is the dynamics of the situation and the

environment.

For example, as part of a product company, you are mostly working on the same product, which has its own

release cycle. The job demands you to know the product well, and in a way it also presents an opportunity to

become a subject matter expert over time. The schedules are a little relaxed, but you have the challenges of

working with huge development and test teams, and manage the document portfolio for your products.

Working with a pure services company is a little more dynamic as compared to a products company. A services

company provides you variety, in terms of the different types of projects, customers, products, technologies, and

so on, but it also comes with tighter deadlines and other challenges.

Finally, working as part of the services organization of a product company combines both the dynamism of a pure

services company and the stability and support of a product company.

SPOTLIGHT—PART I I

“Working as part of the services organization of a product company combines both the dynamism of a pure services company and the stability and support of a product company.”

46

9. Have you ever presented at technical writing learning sessions or annual conferences?

I have not yet presented at any session or conference. However, as part of my present role at MGSI, I plan to

conduct sessions for evangelizing technical communications within MGSI. I also look forward to an opportunity to

share my experience with the technical communication fraternity in the near future.

10. Tell us something about your accomplishments as a technical communicator.

In the last 11 years, I have worked as an instructional designer, technical writer, technical editor, project manager,

and people manager at different levels in different organizations. I have also worked as part of the marketing and

communication teams. I think the “variety” element in my work experience is an accomplishment in itself. It

makes me a true communications professional, and not just a technical writer or an instructional designer or a

technical editor.

11. What suggestions do you have for technical communicators who wish to move into management?

My suggestion is that make a choice based on your skills, and more importantly, your aspirations. Don’t assume

that, as part of natural progression, you will be automatically promoted from an individual contributor to a

manager role. These are two different and parallel paths, each providing its own set of opportunities for work and

growth. And both pay you equally well. So, listen to your heart, analyze, develop your skills and wait for the right

opportunity to knock at your door.

12. You’ve worn the hat of Faculty, Field Support Engineer, Development Executive, Team Leader, Consultant, Senior Writer, Content Lead, Integrated Communications Manager, and Program Manager. Which role did you enjoy the most and why?

There is no easy answer to this. Each role has provided me with something new to learn and grow. However, the

experiences I’ve enjoyed the most are instructional designing, people management, and the experience of

conceptualizing, developing, and managing a new initiative.

SPOTLIGHT—PART I I

“My suggestion is that make a choice based on your skills, and more importantly, your aspirations. Don’t assume that, as part of natural progression, you will be automatically promoted from an individual contributor to a manager role. These are two different and parallel paths, each providing its own set of opportunities for work and growth. And both pay you equally well. So, listen to your heart, analyze, develop your skills and wait for the right opportunity to knock at your door.”

47

13. Who are your favorite bloggers and why?

Sorry, I do not read a lot, but I have started blogging recently. I have always been writing for work: it is only now

that I have started to write for pleasure.

14. Have you interacted with technical communicators from a different geographical location? If yes, how has your experience been like?

Nearly all my roles have involved working with technical communicators and teams across the world. I have

worked with them both offshore and on-site. It has been an amazing experience. In the last 11 years, I have seen a

change in the way the global technical communication fraternity perceives Indian technical communicators. There

were times when we struggled to be treated as equals, but over these years we have matured, and now our skills

as technical communicators have been recognized and appreciated. We are true global citizens and champions of

global delivery, and the world has taken notice of it.

15. Do you read a lot of books? If yes, who are your favorite authors and why?

Sorry, I do not read a lot. I keep myself busy with writing.

16. Finally, any words of wisdom for fledgling technical communicators.

Embrace the right attitude, learn continuously, and take ownership of your work.

~ This interview was conducted by Rahul Prabhakar

SPOTLIGHT—PART I I

“Embrace the right attitude, learn continuously, and take ownership of your work.”

48

WRITER OF THE MONTH 1. Name: Radha Renganathan

2. Email Address: radharenga@yahoo.co.in

3. Current Organization: Financial Software and Systems (FSS) Pvt. Ltd., Chennai.

At FSS, I’m responsible for developing the documentation set for the company’s

Merchant Acquiring and Payment System.

4. Technical Writing Experience: About 3.5 years

5. Awards and distinctions in technical writing: None so far.

6. Are you proactive on TWI? Do you read the group mails regularly?: Yes,

I follow each post on TWI and participate in the group activities. TechCraft makes

for a very good read.

7. Do you believe in community service? How do you wish to contribute as a technical writer?: Yes, I strongly believe in community service. On the TWI

forum, many experts lend their helping hands to novices. This, in my opinion, is

very heartening to see. I’d also like to share my knowledge and help the writing

community in the same way.

8. Tell us about your hobbies: In my spare time, I listen to Carnatic

music. My other hobbies include sewing, embroidery, crochet, and

handcrafts.

R adha Renganathan has an MSc in Operations

Research and Computer Applications from REC, Tiruchirappalli (Now NITT). With seven years of experience in both software development and technical writing, Radha has what it takes to become a successful tech comm professional. Her first job was with Mascon Global Ltd., Chennai, as a developer. After coding for more than 3.5 years and adorning the Lead role, she decided to take the tech comm route. She hasn’t looked back after that! Just like any other passionate writer, Radha too enjoys any form of documentation—be it API documentation, end-user documentation, or writing content for brochures, data sheets, or newsletters. Not only that, she’s adept at template designing and formatting.

49

1 . Rahu l P rabhaka r • Chief Editor

• Layout and Design

• Graphics

• Interview Coordinator (Shivabalan S, Sameer

Chhabra)

• Production

3 . Sumedh Nene • Co-editor

CONTRIBUTORS

TechCraft is one of India’s leading eNewsletters on technical writing. It is our own way of communicating with the technical writing fraternity throughout the world. In case you wish to submit an article for the upcoming issues, email to rahulprabhakar@msn.com This forum reaffirms that we are, because of your undying faith in us. We sincerely hope that with each passing day, you are able to associate with us in a better way. Since this forum is growing by the day, with new and experienced writers joining in from all walks of life, more and more people will definitely be benefited by this enriching experience.

2 . Mousumi Rao • Copy Editor

50

4 . An ind i ta Basu • Co-editor

5 . Abha Iyengar • Co-editor

CONTRIBUTORS

TechCraft is one of India’s leading eNewsletters on technical writing. It is our own way of communicating with the technical writing fraternity throughout the world. In case you wish to submit an article for the upcoming issues, email to rahulprabhakar@msn.com This forum reaffirms that we are, because of your undying faith in us. We sincerely hope that with each passing day, you are able to associate with us in a better way. Since this forum is growing by the day, with new and experienced writers joining in from all walks of life, more and more people will definitely be benefited by this enriching experience.

6 . E l i zabe th R i cha r d son • Co-editor

51

CONTRIBUTORS

TechCraft is one of India’s leading eNewsletters on technical writing. It is our own way of communicating with the technical writing fraternity throughout the world. In case you wish to submit an article for the upcoming issues, email to rahulprabhakar@msn.com This forum reaffirms that we are, because of your undying faith in us. We sincerely hope that with each passing day, you are able to associate with us in a better way. Since this forum is growing by the day, with new and experienced writers joining in from all walks of life, more and more people will definitely be benefited by this enriching experience.

7 . Nee ra j Ja in • Quizmaster, TWI Bimonthly Quiz