Your SlideShare is downloading. ×
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)
Upcoming SlideShare
Loading in...5
×

Thanks for flagging this SlideShare!

Oops! An error has occurred.

×
Saving this for later? Get the SlideShare app to save on your phone or tablet. Read anywhere, anytime – even offline.
Text the download link to your phone
Standard text messaging rates apply

TechCraft - India's leading eNewsletter on Technical Writing (April 2009, Volume 41)

2,840

Published on

TechCraft is India's leading eNewsletter on Technical Writing.

TechCraft is India's leading eNewsletter on Technical Writing.

Published in: Career
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total Views
2,840
On Slideshare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
11
Comments
0
Likes
0
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
No notes for slide

Transcript

  • 1. From the Editor’s desk: 1-3 In Focus: 4-7 Tools: 8-13 Directions: 14-16 Reflections: 17-21 Legally Bland: 22-24 Confessions: 25-29 The Master Speaks: 30-37 Spotlight: 38-42, 43-47 Writer of the Month: 48 April 2009 Document Review Special Issue Volume 41 F R O M T H E E D I TO R ’ S D E S K ( G U E S T POST) S t ay i n g S a n e w i t h S a n i t y C h e c k s We’ve all heard of, and most likely experienced the full brunt of Murphy’s Law sometime or the other. You know that anything that can go wrong, usually does. How many of us have reviewed, peer reviewed, and then re-reviewed a document just that S umedh is a senior technical writer and trainer. His company, CrackerJack one extra time, to realize that you’ve forgotten to update the copyright year, a day after the document was picked up by the final build? Unfortunately, this is more WordSmiths, offers technical common than is necessary, and I say it doesn’t have to be that way. It does need to be writing and training services to managed, however. I’m going to explore the Sanity Checks as a way of filtering out the clients in India, Canada and the unseen errors, even after the review cycles are complete. I will do so in form of some United States. During his career, most likely questions. he has worked in Europe, Australia, India, Singapore, and the United States. He has • We are a team of several writers, developers, and QA engineers with a recently relocated to Toronto, solid review process. Aren’t sanity checks just a big overhead for me? Canada. He has a rich experience of nearly 15 years in all aspects of documentation life cycle from No, they are not. Your review cycles will take care of typos, grammar, missing design to implementation in content, and inaccurate technical details. However, sanity checks catch errors that, software and high-tech as a writer, are your responsibility. They ensure certain things that are not part of environment. He can be contacted at any reviews, don’t fall through the cracks. I will address these in the next question, sumedh.techwriter@gmail.com. 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. 1
  • 2. F R O M T H E E D I TO R ’ S D E S K • What should be the scope of sanity checks and any tips on managing them? There is no single formula for a successful sanity check. Every writer in your team should prepare his/ her own sanity checklist. List all the individual tasks you need to perform on a single document from start (planning) to finish (deployment). Include in this list any step you know you consistently forget. For example, many writers forget to update the Table of Contents (TOC) while rendering the finishing touches to a document. This is not such a big concern half way into the release, but not very nice when it happens in your final check-in for a major release. Another thing writers often forget is updating copyright year, build, version numbers, and the likes. Each of these should be on your checklist as separate entries that you actually check off as done, as you go along the list for each document in your docset. 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. You can use the following sanity checklist to start with and enhance it as you progress through your career. The idea is to capture everything you need to do to make your guide as useful as possible for your readers. Add, modify, and delete from it on an ongoing basis. I would strongly recommend you build a master checklist and customize it for every project or document you work on. Figure: A Sample Sanity Checklist “There is no single formula for a successful sanity check. 2 Every writer in your team should prepare his/ her own sanity checklist.”
  • 3. F R O M T H E E D I TO R ’ S D E S K • What is the right time for sanity checks? Sanity checks should be the last item on your to-do list before checking-in the final version of your guides and documents into your versioning system. Make sure you are through with all your planned review cycles, have incorporated all the comments, and have received a signoff on the linguistic and technical accuracy from people concerned before you go through your final sanity checklist. Ideally and depending on the size (length) of the document, set aside 1-2 days for the sanity checks per document. You are very unlikely to need this much time, but since time is never on the (technical) writer’s side towards the end of a release, it can come in very handy, 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 “If you are a new writer, it is best to build sanity checks into your system now so they become a habit. If you are a more mature writer but have somehow kept your 3 distance, now would be a good time to get cozy with them.”
  • 4. IN FOCUS “ M a k i n g a M a r k ” a s a Te c h n i c a l Editor or Reviewer Many members of the technical communications fraternity fret over their career progression, especially when managerial positions are few and in the passing. If involved in such a discussion, I usually assert that the next logical step for a technical writer or T his article is written by Aneesha Myles Shewani, a Lead - Technical Editor with author is to become a technical editor or reviewer. I take this stand by reflecting on two prominent aspects: first, the significance of review and editing for quality Fiserv, Noida, India. She has a deliverables in documentation, and second, the recognition of reviewing and editing as rich experience of nearly 9 years, a competency that is developed and enhanced over a period of time. having started her career with content writing for Times I believe that the field of technical review and editing is not only professionally Internet Limited, and then moving into technical documentation for rewarding but also adds immense value to technical documentation. It is a benchmark organizations like Infogain and for a writer’s maturity and competency, and also a position of immense responsibility. Computer Sciences Corporation. Contrary to popular myth, editing is not only about marking corrections, or She has worked primarily in the faultfinding; it is about total involvement in a documentation assignment, including domain of insurance and risk management, and payment and planning, collaborating, and defining best practices. industry products. Apart from being extremely passionate about The responsibilities of a technical editor include: technical writing and editing, as a profession and an art, she also has a penchant for creative Planning writing and regularly maintains • Understanding the aim and audience of a documentation assignment her blog. In January 2009, one of her works of fiction, “The Muse” was published in “The Eleven”, a collection of short stories by bloggers, giving further impetus to her love for reading and writing fiction. 4
  • 5. IN FOCUS • 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 “I believe that the field of technical review and editing is not only professionally rewarding but also adds immense value to technical documentation. It is a benchmark for a writer’s 5 maturity and competency, and also a position of immense responsibility.”
  • 6. IN FOCUS The planning, collaborating, and analyzing responsibilities provide on-the-job training for a documentation manager’s role. It opens one’s perspective to challenges of good documentation, the need and pressure of working with various stakeholders within specified deadlines, collating and analyzing data to generate appropriate metrics, and most importantly, accountability for the quality of a deliverable. With regard to the responsibility of writing, a good technical editor can be a fine mentor by showcasing good writing samples or depicting through actual writing, what is expected from the technical writers. Vague marks, comments, or even suggestions can only compound the writer’s confusion, especially if the writer is new. A good editor can always rewrite some sections or sentences and provide positive reinforcement to the writers by giving them examples to follow. Many technical writers get promoted to editorial and reviewer roles and their greatest asset is the knowledge of a particular product or domain and hence, they can immensely contribute to a document by writing the descriptive sections or adding to the information provided by the writer. The challenge in the current industry scenario is to recognize the significance of technical editing and reviewing. Documentation teams have to move from methodologies based on self-review and peer-review to a more professional approach, where technical editing is developed as a competency. Organizations, which want to witness serious and substantial growth in their technical documentation portfolio, should focus on creating a level for technical editors in their designation-competency matrix. Talking in terms of challenges, there is another that waylays the enthusiastic technical editor or reviewer—resistance from within the documentation team. It is a fact that not many people are open to scrutiny and defect-identification in their writing. Most technical writers are used to working independently, and as is typical to writers of all genres, deem what they have written as correct, precise, and comprehensible. With due respect to all technical writers, the other fact is that we all make mistakes! If you are a technical writer, you cannot deny that there have been times when you revisited a document and caught a little mistake here and a tiny glitch there, or just muttered under your breath, “I wish I had more time to self-review this document, but for that ghastly deadline ….!” It is here that a technical editor can be your knight in shining armor and help you eliminate oversight, improve the usability and quality of documents, and provide you a handy reminder of errors and mistakes that you can easily eliminate in your next deliverable. “A good editor can always rewrite some sections or sentences and provide positive reinforcement to the writers by giving them examples to follow. Many technical writers get promoted to editorial and reviewer roles and their greatest asset is the knowledge of a particular product or domain and hence, they can immensely contribute to a document by 6 writing the descriptive sections or adding to the information provided by the writer.”
  • 7. IN FOCUS 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 “The better your track record as a technical writer, the better 7 your chances of becoming the technical editor or reviewer for a documentation team!”
  • 8. TO O L S A n I n t r o d u c t i o n t o D I TA 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 S hashi Prabha studied to become an Electronics and cross-company DITA architecture. When DITA was released as a public XML standard in 2001, IBM contributed the DITA Open Toolkit, the first DITA-compliant processor. Communication engineer, but In March 2004, IBM donated DITA to OASIS (Organization for the Advancement of luck had better plans in store Structured Information Standards), where it is now managed by the OASIS DITA for her. She has a Bachelor of Technology degree from Technical Committee. In April 2005, OASIS approved Version 1.0 of the DITA N. I. T. (formerly known as specification. R. E. C.), Surathkal. After graduating, Shashi decided to expand her skills and Overview knowledge by working as a The name “DITA” has been derived as follows: faculty member at Aptech, • Darwin: Named after Charles Darwin because the topics in DITA can be Chennai. Later, she worked as specialized to inherit properties of the basic topics. a technical support executive at CLi3L e-services • Information Typing: DITA was designed for technical information based on Limited, Bangalore. She built information architecture of Concept, Task, and Reference. upon her experience by • Architecture: DITA is a model for extension of both design and processes. diversifying into technical writing—beginning with a brief stint at TCS, Bangalore. At present, Shashi works at Integra, Bangalore, where she is involved in the documentation of mobile telecommunication products. Her primary interest lies in API documentation. 8
  • 9. TO O L S Writing in sections is the traditional way of handling information. Creating DITA content consists of writing “topics” and “maps”. A “topic” in DITA is a unit of information which is meaningful when it stands on its own. Topic files can have the .dita or .xml extension. Topical writing does not imply any structure at the start. Nor do authors have to consider how all sections will be nested properly. Topics can later be nested and linked in a separate navigation map describing the context of all topics. The following are three basic topic types in DITA: 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: <task> <title> <shortdesc> <prolog> <taskbody> <prereq> <context> <steps> <example> <postreq> <result> <related-links> • Concept: Concept topics introduce the background or overview information for task or reference topics. They should not describe task or reference information. A single concept topic should explain one concept only. “Topical writing does not imply any structure at the start. Nor do authors have to consider how all sections will be nested 9 properly. Topics can later be nested and linked in a separate navigation map describing the context of all topics.”
  • 10. TO O L S The structure of a concept topic is as follows: <concept> <title> <shortdesc> <prolog> <conbody> <section> | <example> <related-links> • 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: <task> <title> <shortdesc> <prolog> <taskbody> <prereq> <context> <steps> <example> <postreq> <result> <related-links> “Reference topics provide quick access to facts. They describe product features, commands, and so on. Information needed for deeper understanding of a reference topic or for 10performing related procedures should be provided in a concept or task topic.”
  • 11. TO O L S 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: <map> <topichead> <topicref> <reltable> <anchor> <navref> <topicgroup> <topicmeta> DITA maps separate content from context. They build a relationship table to generate “related topics” links and set properties of the topics at positions within the hierarchy. They also provide multiple views on the same topics: by product, by task, by topic type, by audience, and so on. “DITA is integrated into and actively supported by many 11state-of the-art XML tools, such as Epic Editor, XMLSpy, Serna, WorldServer Open Topic, and Content Mapper.”
  • 12. TO O L S 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. “The DITA Open Toolkit, or dita-ot, is a free and open-source implementation of the OASIS DITA Technical Committee’s 12specification for DITA DTDs and Schemas. It transforms DITA topics and maps into PDF, HTML, and Online Help.”
  • 13. TO O L S A reference implementation toolkit for both the developerWorks and OASIS 1.0 versions of the DITA DTDs/ Schemas is available at the DITA Open Toolkit project site on SourceForge: http://dita-ot.sourceforge.net. 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 “A reference implementation toolkit for both the developerWorks and OASIS 1.0 versions of the DITA DTDs/ 13Schemas is available at the DITA Open Toolkit project site on SourceForge: http://dita-ot.sourceforge.net.”
  • 14. DIRECTIONS A B u g ’ s L i f e : H o w t o M a k e Yo u r E d i t o r ’ s L i f e — a n d Yo u r s — S i m p l e r What the heck are you talking about? Yes, this article is inspired by the animation movie with the same title. T his article is written by Sridhar Machani, a technical communicator at In many ways, a technical communicator works like a bug (or an ant). For instance, there’s a line (style and authoring guidelines) that you must stick to. As soon as you Siemens PLM Software, Pune, deviate, a supervisor (editor) beats you back to the line (conform to standards). India. He is part of the editorial team of INDUS, STC India Chapter’s newsletter. Sridhar Thankless Job is also an active blogger. He For most people, an editor’s is a thankless job. You get credit for good writing, but an maintains a popular blog on editor gets brickbats if something goes wrong. He/ she is doing his/ her job, that is, to technical communication. You identify and point out your (writer’s) errors. He uses editorial markups, and to make can read his blog posts here. matters worse, the markups are in red. Would you like someone hovering around you all the time—ready to paint your work in red? Did you say, “Aye?” I didn’t think so. 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. 14
  • 15. DIRECTIONS 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). “Contest and argue with the markups, not the person. Be 15 humble and accept your mistakes.”
  • 16. DIRECTIONS A Simple, Happy Life ~ Sridhar Machani “All writers edit their writing to some extent. While you’re at it, ensure you keep an eye on standards and procedures: they’re 16 there for a reason.”
  • 17. REFLECTIONS How to Evaluate Entr ies Every year I have to instruct judges in our local STC technical communication competition on how to evaluate entries. Here is what I tell them: When you evaluate entries, wear your audience hat. That is, determine the audience of R ichard Mateosian began his career as a mathematician. He earned a the entry, and then try to think like a member of that audience. Entrants provide information about the audience and purpose of their entries. Read this carefully, and supplement it with your own understanding. PhD in math from UC Berkeley in 1969. Starting while he was still in graduate With the audience hat firmly on your head, decide what the entry ought to accomplish. school, he spent about fifteen Ask yourself what information it should contain, what navigation it should provide, years as a programmer and what it can assume and what it should explain, and so forth. The answers to these systems development manager. In 1979 Richard wrote questions become the basic framework within which you view the entry. Base your Programming the Z8000, evaluation on how well the entry communicates within that framework. which launched him into ten years as a technical marketer for high-end microprocessors. Having established a judging framework in this way, you can look at the STC criteria Since the early 1990s, Richard for entries of this type to help focus your attention on details, but always remember has worked exclusively as a that the big picture is more important than details. Your objectives in evaluating the technical communicator. He entry are: specializes in writing for an audience of programmers. He • Recognize and provide positive feedback for the ways in which the entry succeeds is active in STC, where he has in meeting the objectives you set for it. been part of the Berkeley • Identify, and spell out ways to improve, areas in which the entry falls short Chapter leadership for many years. He has also been active of the objectives you set for it. in the Northern California regional technical communication competitions. 17
  • 18. REFLECTIONS 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. “The main point of the comments you write is to provide valuable feedback to entrants. Imagine that you are responding 18 a colleague who has asked for your opinion on an important to documentation project.”
  • 19. REFLECTIONS 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. “Write Suggestions Diplomatically. Imagine yourself presenting 19 the comments face to face with the entrant.”
  • 20. REFLECTIONS 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. 20 “For points that aren’t so obvious, be a little less direct.”
  • 21. REFLECTIONS 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 “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 21 comments simply, directly, actively.”
  • 22. L E G A L LY B L A N D Ar ticles? I Don’t Need No Stinking Ar ticles! Sometimes I wish the English language didn’t use articles. I also wish I had hot keys for a, an, and the on my keyboard. At my previous teaching position for a hakwon (after school academy) and my current position with a Korean company, articles were and E lizabeth Richardson (Libby) is currently employed as a technical writer at Samsung are the bane of my existence. These simple words that native speakers take for granted seem to make up for half of my editing tasks. Electronics Company Limited in Suwon City, South Korea. She has Even though my position is technically as a writer, I also handle the editing for my small a B.A. in English and an M.S. in technical writing team (three members in total), the manual team, and random Technical Communication from software User Interfaces (UIs). It’s a delicate balancing act to make time to do my own the University of Missouri – Rolla. She can be contacted at writing and edit everybody else’s at the same time to ensure we all meet our deadlines elizabethmrichard- (especially since Koreans are famous for I-need-this-in-five-minutes assignments). son@gmail.com. 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. 22
  • 23. L E G A L LY B L A N D Give the Document a Quick Once-over Before I start any in depth reading or making any major changes, I’ll typically print out a copy and skim through it looking for any glaring errors (e.g., formatting changes, figure labels, alignment issues) that I might miss if I’m editing on the computer screen. Read through the Document Multiple Times I’ve found that if I try to split my attention between content, readability, grammar, etc., I usually miss something. In order to try and prevent this, I read through the document multiple times and try to focus on a different aspect each 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. “I’ve found that if I try to split my attention between content, readability, grammar, etc., I usually miss something. In order to 23 and prevent this, I read through the document multiple try times and try to focus on a different aspect each time.”
  • 24. L E G A L LY B L A N D 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 24 “A bored and unfocused editor doesn’t do anybody any good.”
  • 25. CONFESSIONS Document Review: The Essence of Ever y Document “Ink is better than the best of memory!” Extending the thought behind this old Chinese proverb to suit the modern-day T his article is written by Girish Sharangpani, CEO and founder of The Knowledge documentation specialist, I’d say, when it comes to product documentation, it’s extremely important for you to put ink on paper in a thoughtful manner for a long- Labs. Girish is a proven lasting effect. technology practitioner with expertise in setting up IT According to me, the key to an effective and good quality document is a thorough incubation centers, software development, product review process—one that verifies the accuracy of your content. You could call this marketing, and process by different names; be it self-review, peer review, structured walk-through, or communications. He has over whatever. A lot has been written about these processes. This article does not cover 20 years of experience; any of these, but touches upon the basic essence of a document review process—its predominantly in the information technology space. importance, and the value it adds to your product and business. As a writer, Girish has co-authored technical and Over the last decade or so, there has been a paradigm shift in the mindset of senior research papers on breast cancer, has created posters management across various industrial verticals with respect to product documentation. that were presented in More and more people have started to believe that product documentation is as international conferences, and important as the product itself. However, even as I write this, many product has written patents, FDA, and documents, especially those that cater to the software industry, smack of regulatory documents. He has a graduate degree in advance extremely poor quality in spite of the numerous quality measures adopted by accounting and auditing from organizations. BMCC, University of Pune, and a postgraduate certification in Computer Applications from the same university. 25
  • 26. CONFESSIONS 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. 26“An outstanding document can even make a mediocre product also look good.”
  • 27. CONFESSIONS 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 “Delivering a quality document within a specific timeline is 27imperative. To achieve results, you have to include these aspects of the review process in your workflow.”
  • 28. CONFESSIONS 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. “It is my general observation that these reviews often leave out some important information. The reason is very simple; developers do not want to make themselves look bad finding problems that they should have already fixed. Hence, their participation is self‑relegated to simply answering questions. It 28 therefore very important that as a writer you ask the right is questions.”
  • 29. CONFESSIONS 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 “If you are writing different sets of documents, it is critical that you select the right reviewers. At the end of the day, the most important criteria is not the bells and whistles the reviewers may have, but whether or not they can truly support your 29efforts and deliver based on your requirements...and while doing so, provide qualitative feedback.”
  • 30. THE MASTER SPEAKS Designing an Effective Review Process Whether you’re a writer or editor, coping with review processes is a fact of life. Unfortunately, these processes seem to spontaneously develop over the years, with no seeming logic behind their development. Even where a process has been carefully T his article is written by Geoff Hart. Geoff has reputedly been telling tales designed and developed, the process can gradually become atherosclerotic over the years. At a former employer, we used a well-defined documentation review process (sometimes ending up in that had been developed over the company’s 25-year existence, but that failed to considerable trouble thereby) achieve timely and effective reviews simply because it had become part of the since he was 6, but took nearly wallpaper: everybody knew it was there, but no longer “saw” it and appreciated it. 25 years to realize that he could earn a living at this trade. Since 1987, he’s worked for How can you develop an effective review process where none formerly existed, or IBM, the Canadian Forest reinvigorate an existing process that desperately needs an extreme makeover? By Service, and the Forest understanding the key tasks in any review process, and determining how the unique Engineering Research Institute characteristics of your situation will affect those tasks. In this article, I’ll show you how of Canada. Since 2004, he’s been a freelancer, and only to do this, with a very real likelihood that you’ll end up with a process that is much less occasionally stops complaining painful for everyone. about his boss. Geoff has worked primarily as a technical editor, but also does technical The essential elements of any review process are as follows: writing and French translation. • Write and revise (self-review) the document He claims to have survived • Perform quality control (internal review, external review, or both) a few bouts of managing publications groups with only a • Perform a final review minor need for ongoing therapy. Contact him by e-mail at ghart@videotron.ca or geoffhart@mac.com 30
  • 31. THE MASTER SPEAKS • Obtain management sign-off • Iterate: review the review process. Write and Revise (Self-review) the Document The benefits of careful design are well known to professionals ranging from carpenters to engineers, and most writers are also familiar with the concept. Yet many writers, often because of tight deadlines that lead to skipped steps, don’t take the time to properly plan the documents they’re going to write. This is particularly true of professionals such as engineers and scientists who are forced to write as part of their job, but who are not primarily professional writers. In my experience, hours of time can be saved for each participant in the review process and during each step in the review process through the simple act of planning. For writers, the obvious plan is an outline, and investing some time to develop an outline can generate significant paybacks all by itself. The problem with outlines, of course, is that if they’re flawed, the resulting documents will contain those flaws, and the flaws will propagate through each subsequent phase of the review until someone spots the problem. As a result, you can generate significant return on the investment in this planning stage by rigorously reviewing the outline before anyone begins to write. At a former employer, several colleagues who were first and foremost researchers rather than writers had enormous difficulty planning what they intended to say in their reports. As a result, the reports became long, poorly organized, rambling efforts to present every thought rather than only the key points—and key points were often omitted. The result was that at each step of the review process, from writing to final review, large amounts of time were wasted trying to correct these problems. I solved much of the problem by working with the author right from the start to carefully analyze the goal of the communication and the facts that had to be presented in the document. As the editor in this workplace, the hour or so I spent developing a strong outline saved me many more hours later in the process, generating a clear return on investment for me because the well-designed outline drastically reduced the time required to repair a poor first draft of the document. Others, including managers, quickly recognized the time savings this approach generated for them. My initial success with only a few writers formed the basis for a major change to our document creation process: the new process included a formal planning meeting during which all stakeholders (the author, the editor, the manager responsible for the information development, and the manager responsible for final approval of the document) rigorously reviewed the outline before the author began writing. “In my experience, hours of time can be saved for each 31participant in the review process and during each step in the review process through the simple act of planning.”
  • 32. THE MASTER SPEAKS As a writer, I often joke that I have a compost pile where I store my works in progress: with a little time, what starts out as raw byproducts of the digestion process (to phrase this delicately) soon becomes valuable fertilizer. Authors often forget to set aside this necessary time that would allow them to review their own writing with some critical distance. Indeed, my favorite all-time review comment appeared on a document I received for editing, where the research director’s distinctive handwriting said only one thing: “Have you read your own manuscript?” Clearly, the author had not. Where possible, remind authors to set aside their first draft for at least a day before returning to it and beginning to revise it. Even a short time away from the manuscript provides the critical distance you need to revise it well. Encourage authors, particularly those who don’t write as their primary job function, to plan to include this time in their scheduling. There will always be plenty of other things to keep them busy until they can return to the 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. “Where possible, remind authors to set aside their first draft for at least a day before returning to it and beginning to revise it. Even a short time away from the manuscript provides the critical distance you need to revise it well. Encourage authors, particularly those who don’t write as their primary job function, to plan to include this time in their scheduling. There will 32always be plenty of other things to keep them busy until they can return to the manuscript.”
  • 33. THE MASTER SPEAKS Over the years, I’ve found that performing an editorial review before the technical review offers a large payback. In the absence of such a review, technical reviewers often spend far more time correcting grammar, punctuation, formatting, and other aspects of the writing than they spend focusing on the content. In contrast, providing a well- edited document for review removes all these obstacles to reading, allowing the technical reviewer to focus on the content—which is, after all, their area of expertise. Performing the editorial review first will not entirely eliminate comments related to the quality of the writing, but it will allow reviewers to focus more of their attention on the technical aspects than if their concentration is constantly being interrupted to correct typos. This approach increases both the effectiveness of the review (more technical errors are caught and fixed) and the speed of the review (less time is wasted fixing minor errors), and thus generates an obvious return on investment for the editor’s time. Quality Control: External Review A well-done internal review can catch both major and minor problems, and can create a greatly improved product, but it has one large failing: the people who perform the internal review are highly familiar with the subject they’re writing about, and thus, may not be representative of the typical reader, who will be far less familiar with the specific information. Moreover, organizations gradually tend to develop a set of standard operating assumptions that become part of their subconscious thought process and that subsequently bias how they communicate about a topic. Even experienced editors, who are experts in finding and resolving the problems that arise from assumptions and implicit understandings, are vulnerable to this kind of problem, particularly after many years spent absorbing an organization’s standard practices and assumptions. The fresh set of eyes provided by an outsider external to the organization solves both problems: the reader’s naiveté reveals any problems that result from the implicit assumptions made by the insiders who created the document. External review is an essential part of some publishing processes, particularly in the sciences. For example, it’s not possible to publish scientific research papers in most journals before the manuscript has been exhaustively and often ruthlessly critiqued by experts in the field. In other fields, reports being written for people who have the authority to reject a report or the activity based on the report (e.g., government regulators), and these people can be enlisted as reviewers to ensure that the final report will be acceptable. In the absence of this review, a lucrative contract may not be awarded or a key project may be stalled. In still other cases, external review is a luxury rather than a necessity: the value of the review is recognized, but because of time constraints or other problems, the review is not performed. “A well-done internal review can catch both major and minor problems, and can create a greatly improved product, but it has one large failing: the people who perform the internal review are highly familiar with the subject they’re writing about, and thus, may not be representative of the typical 33reader, who will be far less familiar with the specific information.”
  • 34. THE MASTER SPEAKS As a result of these concerns, a documentation manager or editor should advocate strongly to include some form of external review in the overall review process. To succeed, you must first understand the reasons why these reviews are not being performed. If the key issue is time, then careful planning (scheduling plus project management to track progress towards deadlines) may free up the time required to permit an external review. If the key issue is political, then understanding the politics behind how the organization makes decisions can provide insights into solutions; in one case, the obstacle was embarrassment over the quality of the materials being sent for external review, and the solution was to edit the materials beforehand. And if the issue is nothing more than apathy, sometimes it’s possible to arrange an external review on your own authority, without asking for permission. It’s often the case that managers who won’t formalize the process of external review happily accept the improved quality that results from such reviews—provided that the review process doesn’t interfere with meeting their own deadlines or lead to any problems that require their attention. Perform a Final Review Whether you conduct rigorous internal and external reviews, or only perform some cursory quality control, at least one final review stage is necessary. Since it’s inevitable that some changes will have been made as a result of early reviews, someone must ensure that the author has responded correctly to the review suggestions. Although this can be delegated to the author, my experience has shown that left to their own devices, authors often respond inappropriately, misunderstand review suggestions, or introduce new errors while responding to the reviews. In nearly 20 years of working as an editor, I’ve only rarely found an author with a perfect record; some simply ignore comments they disagree with or misunderstand, and most introduce additional errors even when they respond appropriately. (It’s human nature to grow bored with a document after revising it for the tenth time, and that boredom weakens the author’s focus and inevitably leads to errors.) As a result, the ideal review process includes a final editorial review. This lets you polish the document to a fine glow and produce the maximum possible quality. But at a minimum, this final review gives you one last chance to spot any problems that have made it through all previous stages of the review process. These problems are legion, and cannot simply be assumed to have been fixed; examples include orphaned phrases such as “graphic artist: please replace this figure with a new one” and authors who, knowing that there would be no final review, took the opportunity to slip scurrilous or offensive statements into their manuscript. “In nearly 20 years of working as an editor, I’ve only rarely found an author with a perfect record; some simply ignore comments they disagree with or misunderstand, and most introduce additional errors even when they respond appropriately. (It’s human nature to grow bored with a document after revising it for the tenth time, and that 34boredom weakens the author’s focus and inevitably leads to errors.)”
  • 35. THE MASTER SPEAKS You can understand this part of the process by comparing it with a product assembly line: before a product is boxed and shipped to the consumer, someone always tests it to ensure that it’s working right. For computers, this may involve a 24-hour “burn-in”, with the product turned on for this long to ensure that it won’t burn out as soon as it’s plugged in, supplemented by a suite of software tests that rigorously and automatically test all key features of the installed software; for automobiles, it may involve a test drive from the end of the assembly line to the vehicle transporter that will take the car to a dealer. In traditional print publishing, this final review occurred after layout of the document and was referred to as proofreading (i.e., reading the document as proof that the final results were correct). With modern all-electronic production processes, and particularly with online publishing (e.g., help systems and Web sites), there’s a pernicious assumption that if you’ve carefully controlled the process up to this point, there will be no additional errors to find. I’ve found few editors who believe this to be the case. Indeed, when a former employer suggested doing away with this aspect of the publishing process, I spent a few months documenting (and fixing) the errors that resulted. Despite careful control of quality during the internal and external reviews, and an experienced and skilled desktop publisher, I routinely found dozens of small errors and often more than one significant error that would not have been caught without a final proofreading. Obtain Management Sign-off The final step in any publishing process is some form of management signoff. Depending on the nature of the organization and of the people involved, this step may be a simple “rubber stamp” exercise; in other cases, the manager who will be responsible for the consequences of publishing the document will rigorously examine the document down to the level of individual punctuation. In either case, all the quality control you’ve performed thus far in the process will be justified: if there are no errors for the manager to detect, they will gradually come to trust you, and will spend less time focusing on the minutiae. This makes better use of a manager’s expensive time, avoids costly delays at the end of the publication process, and builds a sense of trust and cooperation. The planning meeting I described earlier in this article is a key success factor. If the manager has carefully reviewed the documentation plan right at the start, this greatly decreases the risk of finding the results unacceptable at the end of the process. In particular, the manager has less incentive to justify their participation in the review process by insisting on major last-minute changes because they have already insisted on these changes at the start of the process. “If the manager has carefully reviewed the documentation 35plan right at the start, this greatly decreases the risk of finding the results unacceptable at the end of the process.”
  • 36. THE MASTER SPEAKS It’s certainly true that sudden insights at the last possible moment can lead to extensive changes in the documentation, and this is one justification for a final management signoff. But more often, the approval task is simple and fast for a document that has survived all the previous steps in the review, and provides yet another example of how building quality and consensus into the initial stages of documentation development pays off with time savings and increased quality later in the process. For products such as software that are evolving continuously, the writing and review process will be repeated (iteration) for the lifetime of the product—as often as twice per year for decades with modern software. For other situations, documents may be revised only occasionally, often after a long delay; this is the case with dictionaries and technical specifications, for example. Iterative review is often seen as a necessary evil, but in truth, it should be seen as a final reality check on your process. Reader reviews of your information between versions provide key insights into what you’re doing right—and perhaps more importantly, into what you’re doing wrong. Developing a mechanism for such reviews permits continuous improvement of the quality of the materials you produce, particularly if you can address those reviews in the down-time between releases of the document. Reader feedback can be difficult to obtain, particularly where you don’t have direct access to these readers. But there are always ways to find out whether the material you’ve produced is meeting expectations. Review articles in the popular press or in specialty magazines are a great source of information, whether you’re producing software or best- selling popular science books. Best-selling third-party books such as the Pogue Press/O’Reilly “missing manuals” often provide keen insights into more effective ways to communicate or things that you’ve missed in your own documentation. If you lacked the time or resources to have your materials professionally edited, why not hire an editor during the down-time before the next writing and review cycle begins? Use the insights provided by that professional to do a better job in your next iteration of the writing. Look for online communities who discuss what you’ve written to see what they’re saying, and ask leading questions to generate discussions about where you’ve succeeded and where you’ve failed. Last but not least, talk to your colleagues in technical support and training. They deal directly with the people who use the information you create, and can provide important insights into where that information fails to meet reader needs. “If you lacked the time or resources to have your materials professionally edited, why not hire an editor during the down-time before the next writing and review cycle begins? Use the insights provided by that professional to do a better job in your next iteration of the writing. Look for online communities who discuss what you’ve written to see what they’re saying, and ask leading questions to generate 36discussions about where you’ve succeeded and where you’ve failed.”
  • 37. THE MASTER SPEAKS Iterate: Review the Review Process This article neglects many important issues that arise from the details of this process. Among other things, each company and context will have certain unique characteristics that change how you look at the review process. For example, sometimes it’s possible to conduct simultaneous reviews of a document to greatly reduce the time compared with sequential reviews. This raises the issues of how to reconcile conflicting review comments and how to obtain the synergies that are possible when reviewers can interact and conduct dialogues as they simultaneously review a document. Tools such as wikis (see, for example, http://wiki.org/) and blogs (e.g., http:// www.livejournal.com/) allow readers and publishers to interactively create and update information, and exciting new tools such as XMetal Reviewer (http://www.xmetal.com/en_us/products/xmetal_reviewer/index.x) will increasingly solve this problem. In addition, as I noted at the start of this article, review processes eventually fossilize with the passage of time, and what was once a powerful living organism transforms into a burdensome chunk of stone. Periodically, the stakeholders involved in any review process should take the time to confirm that it is still serving its intended purpose, and that people are still following the process. An organization’s context may have changed, requiring the addition of new review steps (e.g., by the organization’s lawyer, to confirm compliance with new regulations) or the removal of old steps (e.g., no more management approval if they trust you to do the job right). Technological change may also let you improve your process. Even if no changes are necessary, the dialogue between stakeholders that results from this review process is itself valuable because it keeps the lines of communication open and instills a sense of teamwork that is often lacking. My goal in writing this article is not to suggest that reviews are easy, but rather to explain the goals and constraints of the key components of a review process. In so doing, I’ve illustrated how to take advantage of each phase of review, while minimizing its constraints. As my examples have shown, you can obtain remarkable payback from investing the time to understand the process and to look for ways to make it work better. I encourage you to explore some of the ideas I’ve presented, and to report your results to readers of this magazine. I look forward to your insights! This article has been reprinted with permission from the author. Previously published as: Hart, G. 2006. Designing an effective review process. Intercom July/August 2006:18–21. ~ Geoff Hart “Review processes eventually fossilize with the passage of 37time, and what was once a powerful living organism transforms into a burdensome chunk of stone.”
  • 38. S P O T L I G H T — PA RT I Inter view with Shivabalan S 1. Tell us something about your education. Did you study to become a writer? I am a BA English graduate. I did not study to become a technical writer, but more S hivabalan has been a part of the tech comm industry for close to 12 years now. His to get into Journalism. documentation expertise includes 2. When did you realize you were a writer at heart? writing User Guides, Help Systems, and Release Notes. He I realized this during my first work stint. I was asked to write a White Paper on has a strong multicultural one of the products we were working on. Though it looked like there wouldn’t be background, having worked in Malaysia, the United States, India, even a page worth of content, I actually ended up writing five pages of relevant and Indonesia. He is currently content. This experience made me look out for specialized roles in writing. managing a team of documentation support personnel at Dell India R&D. 3. How did you secure your first gig as a technical communicator? You can contact him at Shivabalan_S@dell.com. It was a challenge; I failed more than three interviews initially, given the lack of experience. I then took about a week to prepare from my failed experience, by brushing up my English language skills, looking up existing manuals, and understanding the basics of documentation life cycle. This preparation helped me in securing my first writing job. 38
  • 39. S P O T L I G H T — PA RT I 4. What challenges did you face as a technical communicator? Pretty much the same as most other technical communicators; lack of access to the product I was documenting, incomplete design documents, not enough time with developers and testers to give me interviews, ever-changing schedules, and interestingly, lack of processes in a couple of companies. 5. What efforts did you make to overcome these obstacles? I worked with engineering managers for getting access to prototypes, to an extent that solved the problem of understanding the product features and its workflow. After that, I tracked incremental changes to the product features by using a spreadsheet. This way I didn’t miss documenting any feature. As for technical interviews, I worked with the developers to give me time. And after they committed, I put them on their calendars, copying their managers. This also, to an extent, helped me get time with them to answer my questions and review my drafts. Companies where there were no processes were companies where there were no dedicated writing teams as well. I relied heavily on the Project Managers to set up ad hoc processes. I created documentation plans, covering the documentation deliverables, schedules, risks, and their mitigation plans, and shared the plan with the team. The documentation plan helped set up an interim documentation process for me. 6. Tell us about your work experience. List the companies you have worked with to date. I have now close to twelve years of technical writing experience, with work assignments in India, the United States, Malaysia, and Indonesia. I have worked with Eastern Software Systems, Global Software Technologies, HTC Software Development Center, Satyam, Oracle, and now, Dell India R&D. 7. How is it working as a Documentation Manager at Dell India R&D? Describe a typical day at work 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 “Working as a Documentation Manager at Dell India R&D is 39 full of challenges, yet enjoyable.”
  • 40. S P O T L I G H T — PA RT I releases going almost every month. And it is a huge challenge to provide documentation for each of their products. Our schedules are set on stone, so we do not get any leeway for slipping dates. It requires constant juggling to make sure that the documentation sets keep hitting the right dates. And that pretty much describes a typical day at work for me; keeping an eye on all projects, tracking team members’ achievements, their strengths and development opportunities, and mentoring them when required. 8. Describe the differences between writing and managing. What skill sets are required to succeed in each of these profiles? The ability to communicate (written as well as spoken) easily using the English language, the ability to understand business context (about why the project or product is being developed), and the ability to lucidly explain key features and workflow to end users, are the primary skills required for a technical writer to succeed. Managing people is a different ballgame altogether. One has to coach novices, keep track of their performance, resolve conflicts within the team, and be able to see the big picture and strategize accordingly. 9. What similarities or differences did you find in working for a product company (Oracle) and working for a service company (Satyam)? I can only comment on the differences, not the similarities (except that schedules were followed aggressively in both the setups.) Product companies usually have well–defined documentation processes and teams, because their products are accompanied with supporting documentation. Writers working for such companies are exposed to both templates and style guides. On the other hand, service companies ask for documentation only if their clients require it. Such companies depend more on ad hoc processes, or worse, no processes! So, it is that much more a challenge to get a developer’s time, to get access to completed design documents, and to come up with templates. “The ability to communicate (written as well as spoken) easily using the English language, the ability to understand business context (about why the project or product is being developed), and the ability to lucidly explain key features and workflow to 40 users, are the primary skills required for a technical writer end to succeed.”
  • 41. S P O T L I G H T — PA RT I But I believe most service companies have now started recognizing the importance of documentation and are providing equal importance to it. 10. Have you ever presented at a technical writing learning session or an annual conference? 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. “To move into people management, technical writers must have good rapport with their team members. They should be creative, be able to think out of the box, and be able to see the big picture. They should also be able to align their team 41members’ goals with the organization goals to create a win-win situation for all.”
  • 42. S P O T L I G H T — PA RT I 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 “While writing, think like your end user and play with the product as much as possible; this will greatly help you in fully 42understanding the product while coming up with relevant content.”
  • 43. S P O T L I G H T — PA RT I I Inter view with Sameer 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, S ameer Chhabra is an experienced technical communicator, who has been 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 working in the IT industry for more than 11 years. He started and mainly through in-house trainings. his career as a faculty member at the NIIT Ludhiana Center and 2. When did you realize you were a writer at heart? presently works as a Program Manager at Microsoft Global Ser- vices India (MGSI) in Hyderabad. After I started to write stuff other than what was required at work. Sameer has a rich experience in program management, project 3. How did you secure your first gig as a technical communicator? management, and people management, in addition to It was sometime in 1999. I was already a Microsoft Certified Systems Engineer technical editing, technical working with an Internet Service Provider, but still trying to wrap up my last writing, and instructional design. He is a Microsoft Certified semester at NIIT. I saw a poster at the NIIT center, asking people who knew Systems Engineer (MCSE) and a English, to apply for a job as an instructional designer with NIIT. It was the first member of the Society for time I heard about this profession. I enquired a little more and figured out that Technical Communication (STC) the job required writing about technology and technical subjects. It was a India chapter. He can be reached at sameer.chhabra@live.com. great opportunity for me. 43
  • 44. S P O T L I G H T — PA RT I I 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. “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 44your attitude. Take every challenge as an opportunity to learn, perform, and grow.”
  • 45. S P O T L I G H T — PA RT I I 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. “Working as part of the services organization of a product company combines both the dynamism of a pure services 45company and the stability and support of a product company.”
  • 46. S P O T L I G H T — PA RT I I 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. “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 46skills and wait for the right opportunity to knock at your door.”
  • 47. S P O T L I G H T — PA RT I I 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 47“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 R adha Renganathan has an Merchant Acquiring and Payment System. MSc in Operations Research and Computer 4. Technical Writing Experience: About 3.5 years Applications from REC, Tiruchirappalli (Now NITT). With seven years of 5. Awards and distinctions in technical writing: None so far. experience in both software development and technical 6. Are you proactive on TWI? Do you read the group mails regularly?: Yes, writing, Radha has what it I follow each post on TWI and participate in the group activities. TechCraft makes takes to become a successful tech comm professional. Her for a very good read. first job was with Mascon Global Ltd., Chennai, as a 7. Do you believe in community service? How do you wish to contribute as developer. After coding for a technical writer?: Yes, I strongly believe in community service. On the TWI more than 3.5 years and forum, many experts lend their helping hands to novices. This, in my opinion, is adorning the Lead role, she decided to take the tech comm very heartening to see. I’d also like to share my knowledge and help the writing route. She hasn’t looked back community in the same way. after that! Just like any other passionate writer, Radha too 8. Tell us about your hobbies: In my spare time, I listen to Carnatic enjoys any form of documentation—be it API music. My other hobbies include sewing, embroidery, crochet, and documentation, end-user handcrafts. documentation, or writing content for brochures, data sheets, or newsletters. Not only that, she’s adept at template designing and formatting. 48
  • 49. C O N T R I B U TO R S 1.Rahul Prabhakar • Chief Editor • Layout and Design • Graphics • Interview Coordinator (Shivabalan S, Sameer Chhabra) • Production 2.Mousumi Rao • Copy Editor 3.Sumedh Nene • Co-editor 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. 49
  • 50. C O N T R I B U TO R S 4.Anindita Basu • Co-editor 5. Abha Iyengar • Co-editor 6.Elizabeth Richardson • Co-editor 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. 50
  • 51. C O N T R I B U TO R S 7 . N e e r a j Ja i n • Quizmaster, TWI Bimonthly Quiz 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. 51

×