VolXII, Issue 4

Putting forth this issue of INDUS has been a series of challenges. When one problem seemed solved, another cropped up. At many points, the only way out was the easy way out – giving up. But then again, why let the hurdles defeat us? And it’s only in the face of challenges, that we learn new things, new techniques. We find out how many people are willing to stand up and help get things done. And look how that turned out – we have a BUMPER issue for you this time – with an unprecedented ten (yes ten!) new articles for you to devour. And that is not counting the regular features.

So let’s get straight to what’s in this issue for you. First of all, we’re starting a three-part series on Ratio Analysis and Estimation courtesy of Makarand. The first part is in this issue, keep watching this space for subsequent parts.

Prabu explains the concept of Content Marketing.

If you recall the last issue, we had an article by Sumedh about his experiences as a newcomer in Canada. In this issue, he tells you what you should be doing if you are serious about looking for a tech writing job in Canada.

Continuing our series on tips for using tech writing tools, is Smitha. She has some tips for Captivate users.

Anindita’s wisdom speaks through her article on age-old tech writing myths. Watch her expertly bust some myths with her sharp pen!

Vikrant has some ideas on creating portfolios. Read his article to know what you should be doing right away!

Sharada tells you how she keeps up with the latest technologies… are you taking notes?

After a long time, we have a book review – Prasanna tells you what to expect in Lipton’s Practical Guide to Information Design.

Rajdeep has a quick report on the recently concluded Regional Conference that STC India organised in Bangalore. Ramesh also has a report – but this one is on the Author-it workshop that STC India organised in Pune.

For this issue, we have two very talented illustrators climbing on board – Nirupama Singh (Graphic Designer at Siemens PLM) and Vishesh Gupta (Tech Writer at ST Microelectronics). I’m sure you’ll enjoy the color they have brought to this issue as much as we did.

In the regular features we have the STC Announcements, STC India Announcements, and the city-specific Learning Session updates. Last, but never the least, STC India President, Michelle, wants an audience with you. Lend her an ear, won’t you?

Anagha Chandratrey,
On behalf of the INDUS team.

If you want to write for INDUS, check out the authoring guidelines and send in your articles to the editor before the 10th of October, 2010.

Possibly related articles:

1. Jan-Feb 2010 Newsletter
2. Aug-Sep 2009 Newsletter
3. March-April 2010 Newsletter

– Makarand Pandit

This is the first essay of a three-part series.

There are three essential attributes of a communication product. These are Content, Structure, and Presentation. In a well-developed communication product equal importance has to be given to all of them.

The presentation captures attention, structure makes the content accessible and the content fulfils the information requirement. If any one of these attributes is lacking, the information is not effectively communicated.

While designing the document it is therefore essential to examine the design from all these aspects. The study of these aspects can also help writers and managers during the estimation phase of the project.

In this article I have covered some of the estimation techniques that I think could be useful to all.

Concept of a Rich Content Outline

Preparing an outline is the logical step we all follow before writing the document. However, this outline is often very elementary. If we try to identify more details at the outline level itself, it can be a great help. Since this type of outline can have more information than the typical simple ones, I am calling it a Rich Content Outline or an RCO. Take a look at the Simple Outline and the RCO that I have inserted below.

Notepad User Guide – Typical Simple Outline

Chapter 1: Introduction to Notepad

Need of Word Editors

Advantages of Notepad

Limitations of Notepad

Types of files Notepad can be used to edit

Chapter 2:  Getting Started with Notepad

Starting Notepad

Typing text

Saving the newly created file

Opening Notepad help

Closing Notepad

Notepad User Guide – Rich Content Outline

Chapter 1: Introduction to Notepad

Need of Word Editors

Information Organization Pattern: General to specific

Graphic: A person working on a computer

Table: None

Procedures: None

Cross-References: Advantages of Notepad

Advantages of Notepad

Information Organization Pattern: Most Important to least important

Graphic: None

Table: None

Procedures: None

Cross-References: Limitations of Notepad

Limitations of Notepad

Information Organization Pattern: Most Important to least important

Cross-References: Advantages of Notepad

Types of files Notepad can be used to edit

Information Organization Pattern: List sorted by well-known to least-known

Cross-References: URLs of resources related to Notepad on Internet

Comment: Mention about Notepad 2007 (The XML editor)

Chapter 2:  Getting Started with Notepad

Starting Notepad

Information Organization Pattern: Whole to parts

Graphic: Notepad Window with callouts showing Menu Bar, and Text

Table: Menu Description

Procedures: Starting Notepad from Programs File

Cross-References: Closing Notepad

As you can see the RCO is far more detailed. In the RCO along with the heading we also identify the following

• Information Organization Pattern
• Graphic to be used
• Table to be inserted and information contained in it
• Procedures to be included in this heading
• Cross-References to be mentioned
• Comment giving some more information

The RCO thus provides a precise and detailed understanding of the contents to be written.

Advantages of RCO

• RCO is “a rich outline” with more focus on explanation of the contents.
• It leads to better understanding of the product being documented.
• It can demonstrate to a much greater detail what exactly the document will contain and what it won’t.
• It can be used to finalize the scope of work and get a sign-off from the project sponsor (manager or client) before the project begins.
• It is an excellent tool for knowledge transfer (amongst the team of writers.) After preparing the RCO any other writer can pick up the outline and prepare the document easily.
• It clearly indicates the resources needed to complete the document (for example, screenshots, specially designed graphics, list of links, and so on.)

How to prepare a Rich Content Outline

Step 1 – Prepare the conventional simple outline

Step 2 – Identify the information patterns

Choose from the following commonly-used patterns.

• Chronological – Useful for procedures and processes that
• Psychological – Useful for arranging information based on a particular type of audience and what that person could be looking for
• General to specific – Useful for introducing concepts or new products
• Problem to solution – Useful for chapters like trouble-shooting, error-handling, and so on.
• Whole to parts – Useful for explaining GUI, machinery
• Most important to least important – Useful for arranging items in a sequence, such as lists, tables, and so on.
• Comparison/Contrast – Useful for explaining newly added features or explaining something on the basis of something else that the audience may already know

Step 3 – Identify other information for every topic. This will include graphic ideas, information to be put in tables, cross-references, links, and so on.

Step 4 – Write down the comments for every topic, as required.

Step 5 – Review the entire RCO and make changes if necessary.

Once the RCO is ready share it with the team members and get it approved.

You can then use the RCO to prepare estimates and project plans. In the next part of this article series we will talk about some estimation techniques.

Possibly related articles:

1. Adopting Documentation Usability Techniques to Alleviate Cognitive Friction

- M.D.S.PRABU

The rules of marketing undergo significant changes, as time passes by. From a seller-dominated market to a buyer-dominated market, it has come a long way to ultimately crown the consumer. Other ancillary functions like marketing communication and advertising undergo a sea-change. So, “blowing one’s trumpet” is no more the way of selling, as everyone, right from the consumer to the competitor, is well equipped with information, facts, and figures.

The dramatic shift in marketing is characterized by the advertising language that uses the tone of informing than selling. In today’s world a seller needs to be proactive, anticipate changes, and create awareness among the community. To reach everyone in the right time, place and to convince and provide a multitude of options is the goal of every seller and marketer. Content Marketing empowers one to do that.

What is Content Marketing?

Content Marketing is the creation of engaging, compelling, and customer-centric content, effective use of various modern media (internet, website, blogs, social media marketing) to communicate the focused information to target buyers. Content marketing is an improvement over traditional marketing (print, advertising, and magazine) and yields fantastic results at nominal investments and minimal maintenance costs.

To be explicit, content marketing involves viral marketing for your campaigns – remember the SMS virus created by BJP asking people to vote them to power, during the 2004 elections or the electoral magic created by Obama through effective campaigning in social networking sites and online media? The intended communication reaches the target audience through the click of a mouse. A successful content marketing strategy involves offering information products to end-consumers. Servicing customers, achieving increased user satisfaction in a highly competitive scenario amidst expanding overseas presence is possible easily through content marketing.

Content Marketing industry

Content Marketing is a multibillion dollar industry. There is a thin line between Content Marketing and Traditional Marketing. It is not a substitute but a supplementary function that improves the effectiveness of the latter, phenomenally. A point to be noted is that most of the newspapers, magazines, and even advertisement agencies and TV channels have established an online presence. Having embraced the philosophy of integrated marketing communication, they are offering the benefits offered by content marketers in addition to what they have been offering from time immemorial. However, there are niche areas like Search Engine Optimization and Pay Per Click (PPC) that only content marketers offer. Content marketing has enormous potential in terms of generating employment opportunities or simply put change the face of marketing.

The competitive edge

Why do the leading television channels play recorded videos of their programs in their websites? Why do magazines publish their news articles online and in social media marketing tools like Facebook? Why do CDs and DVDs accompany the media kits of corporate? Why do companies invest more and more money in creating their own content? Why are regional websites attaining popularity? Why are blogs and twitter posts in the limelight? Limited attention spans, constant urge for information on products are some of the reasons.  Added to that is the viability to access content at any place and time – for instance travelers read mails during flight journeys. Content marketing helps reach the audience conveniently be it during their leisure or while attending a board meeting or even when driving a vehicle. It does not surpass traditional marketing, but helps your target audience access information in the shortest time span. Added to that, other factors like user-friendly language, mechanism of crisp communication and the possibility of providing actionable items are some of the factors that favor content marketing. For instance, there are options to read related posts or contact a subject matter expert by email or chat in most of the websites.

Adopting Content Marketing

A judicious mix of traditional and content marketing will help in achieving your company’s objectives or ROI from marketing budgets. That said, it is not easy to transform the mindset of a company’s top management to publish all their customer-centric information on the internet, or post thought leadership content on their inventions in a public-domain, more so in the case of traditional organizations. But one needs to communicate the success of solepreneurs, multinationals, and even non-profit organizations who have utilized this powerful medium to achieve marketing objectives by spending only a fraction of their marketing budgets. Above all making an effective use of the content marketing devices involves only a one-time investment and thereafter it is only maintenance and content creation costs, for instance in the case of a corporate website all that an organization needs to invest is in buying a domain name and for the initial layout, design etc. Organizations that fail to consider content marketing will lag behind their competitors, no matter the quality of their offerings, reputation in the market or any other factor that has been influential to the organizations growth, till now.

The future of Content Marketing

Content marketing is here to stay. But what will happen to it in the next ten years is anybody’s guess. Just like every technology or invention there will be improvements over Content Marketing. But, until anything of the sort happens, it is an important marketing mix. If you have not yet looked into implementing it in your company so far, it is high time you act upon it.

About the author:

Prabu is working as a content management executive for a software testing company in Bangalore. His email id is prabumds@gmail.com and his LinkedIn profile is http://in.linkedin.com/pub/prabu-subramanian/21/143/a85.

About the illustration:

Used with permission from Mallika Yelandur.

No related articles.

– Smitha V.

Five simple Adobe Captivate tips that help you design, develop, and review your projects quickly.

Create ‘stencils’ for your slides

Master Slide is a new feature in Adobe Captivate 5 that adds ‘stencils’ to your project. If you have common elements that you want to insert on multiple slides, using master slides can greatly help. You can add background images, logos, tag lines, water marks, and more to a master slide. Then, with a single click, you can assign the master slide to as many slides as you want.

You can edit the default master slide or add new master slides to a project.

To edit the default master slide:

1. Click Window > Master Slides. The Master Slide Filmstrip appears.
2. Click the default master slide. The focus on stage now changes to the default master slide.
3. Label the slide and change the background of the slide using the Property Inspector (the pane on the right).
4. Insert images and other objects that you require.

You can edit the default master slide or add new master slides to a project.

Fig 1: Master Slide Filmstrip

To add new master slides, click Insert > Master Slide. The new master slide appears in the Master Slide Filmstrip. Click the slide to bring it on stage and then, change the properties of the slide or add images and objects to the slide, as required.

Fig 2: Insert menu

To make the best use of your stencils, insert new slides into the project using the Insert > New Slide option rather than the Insert > Blank Slide option. When you use the Insert > New Slide option, Adobe Captivate automatically assigns the new slides to the master slide of the slide on stage. Blank slides (Insert > Blank) are not assigned to any master slide by default; you can explicitly assign these slides to a master slide.

To assign a master slide to a slide:

1. Click the slide in the Filmstrip. To select multiple slides, hold down the Shift key and select the slides.
2. In the General section of the Property Inspector, choose the required master slide from the Master Slide drop-down list.

Fig 3: Assigning Master Slides to Slides

Reuse object styles across projects

An object style is a set of visual attributes, such as colors and fonts, which you can assign to an object. Object styles help you maintain a consistent look-and-feel for objects within and across projects.

You can design object styles once and reuse them across projects in one or both of the following ways:

• Create styles at the ‘application’ level instead of at the ‘project’ level. Use this method if you know what styles you need at the outset. For example, you may be required to use your corporate guidelines in all your projects. You can also create ‘application’ level styles at any point in time.
• Export the styles and then import them into other projects. This method is helpful if you have already created the styles in a project and need to use them in other projects.

To create styles at the ‘application’ level:

1. Close all the projects in Adobe Captivate. The Welcome screen appears.
2. Click Edit > Object Style Manager.
3. In the first left column, select the object for which you want to create a style.
4. In the next column, click one of the default styles and then click Clone.
5. Type a name for the style and specify the required parameters.
6. Click OK.

To export and import styles:

1. Click Edit > Object Style Manager.
2. To export a style:
   1. Determine whether you want to export all styles, all styles of a specific object, or a specific style.
   2. If you want to export all styles of a specific object, click the name of the object in the first left column. If you want to export a specific style, click the name of the style in the next column.
   3. Click the arrow adjacent to the Export button and click an appropriate option.
   4. Click Export.
   5. Type a name for the .cps file, browse to the location where you want to save the file, and click Save.
   6. To import a style, click Import and choose the .cps file that contains the style(s) that you want to import.

Fig 4: Object Style Manager

Create and reuse object effect sequences

In Adobe Captivate 5, you can apply multiple effects to objects, for example, you can apply ‘Tint’, ‘Fly In’, and ‘Blur’ effects to a button. To apply the same set of effects to other objects in the project or across projects, save the effect sequence as an XML file and then, apply the XML file to the required objects.

Here’s how you can save the effect sequences as XML files:

1. In the Effects panel (Windows > Effects), click the save icon.
2. Type a name for the XML file, choose a location to store the file, and click Save.

Fig 5: Effects panel

To apply the effect sequence to another object (in the same project or across projects):

1. Go to the slide that contains the object and select the object.
2. In the Effects panel, click fx > Browse. Navigate to the location where you have saved the effect sequence XML file and click Open.

Fig 6: fx menu with the saved effect sequence

After you have browsed and used the effect sequence in a project, a new option Custom appears in the fx menu of the Effect panel. You can now use this effect sequence in Advanced Actions too.

Preview next ‘n‘ slides

While developing large projects, the Next n Slides option in the Preview menu is a great time saver. Using this option, you can limit the preview to a specific set of contiguous slides.

By default, ‘n’ is five, which means you can play the next 5 slides in your project. You can change the value of ‘n’ in the project preferences as follows:

1. Go to Edit > Preferences > Global > Defaults.
2. Change the value in the Preview Next text box.

Consider that you have 100 slides in a project. You are setting up interactivity between 9 slides in the project (say slide 36 to 45). Each time you make a change, preview just these nine slides by assigning the value 9 to ‘n’. How convenient!

Fig 7: Preferences dialog box

Send captions for editing

Here is a quick tip to get all the captions in your Adobe Captivate project edited and to get the changes incorporated in a jiffy.

The captions include:

• Closed captions
• Text captions
• Rollover captions
• Buttons
• Text buttons
• Text captions and rollover captions within rollover slidelets
• Question slide captions and buttons

1. Extract all the captions into a Microsoft Word document. To do so, click File > Export > Project Captions and Closed Captions.
2. Type a name for the .doc file, browse to the location where you want to save the file, and click Save.
3. Send the file to your editor. (If you are editing the project yourself, open the Microsoft Word document).
4. The editor can review the text in the Original Text Caption Data column and type the revised text in the Updated Text Caption Data column.
   Important: None of the other information in the file, such as the slide numbers and slide IDs must be changed as these references are required to merge the changes back in to the Adobe Captivate project.
5. After the review, import the revised captions into your project. To do so, click File > Import > Project Captions and Closed Captions.

Fig 8: Extracted and edited captions in the .doc file

All the captions in your project are replaced with the revised strings in the .doc file.

The .doc file with the extracted captions can be used for localization too. Get your localization team to type the localized strings in the Updated Text Caption Data column. Then, import the .doc file into your project.

Learn and contribute…

If you are just beginning to learn Adobe Captivate or want to know more about specific features, the Adobe Captivate Online Help is an indispensable resource. You can also contribute to the documentation by adding tips and tricks, tutorials, troubleshooting information, or suggestions for improvement; all you need is a free Adobe.com account. Read these guidelines and start contributing right away!

About the author:

Smitha V works as a Senior Technical Writer on the Learning Resources team at Adobe Systems, Bangalore. She has over eight years of experience in technical communication and can be reached at smitha01@gmail.com.

About the illustration:

Used with permission from Vishesh Gupta.

Disclaimer:

All product names, logos, and any trademarks used in the illustrations and elsewhere in this article are for identification purpose only, are the property of their owners, and their rights are acknowledged.

Possibly related articles:

1. Five RoboHelp tips
2. The FrameMaker Five
3. DITA Writing Tips

- Prasanna Bidkar

The Practical Guide to Information design, by Ronnie Lipton, presents the concept of information design and the role it plays in your day-to-day life. The author skillfully identifies different examples and convinces you that information design exists in everything you read from signposts to books and numerous other documents. Ronnie Lipton is the director of Transform and Function, a consultancy firm for writing, editing, design, and multicultural communication. She has also taught at the George Washington University and the University of Maryland. She has four other books to her credit related to communication of information in cross-cultural environments and using graphics and visual cues. In this book, she brings her experience from academia as well as the industry to create a good mix of theory, case studies, and exercises.

In The Practical Guide to Information Design, Lipton evaluates different elements that contribute to information design. Here, true to the book’s title, she steers away from occupying you with information design theory by briefly explaining the goals of information design. After a brief introduction to information design, she really gets you started with the exercises designed to evaluate an information container. The book has three main sections:  Audience, Word Design, and Picture Design. The first two chapters in the Audience section talk about how people perceive information, and the usability issues that the designer must address. Here, Lipton reviews the Gestalt principles and explores the concept of golden mean and use of the Fibonacci sequence in relation to the layout of a page. In the second chapter, Lipton elaborates how to interview your audience, what to look for in your audience and so on. The author also discusses the five Es of usability and reinforces all these concepts with different case studies.

The second section of the book, Word Design, covers the content part of information design. Lipton takes an in-depth look at the type and layout, writing style, and use of color. The “How to work with type and layout” chapter starts aptly with a quote from Miles Tinker, “reading without comprehension is not reading” (91). Lipton here concentrates on how to make text legible with effective use of type, style, and the placement of text. The author continues her use of illustrations and examples to reinforce the theory, with some tips on writing style and use of color in the next two chapters.

Lipton dedicates the last section of her book to picture design. The main idea of this section is to add illustration and pictures to support what is in the text. In this section, she covers use of pictures and suggests strategies to use diagrams and captions and labels to help the user find the information. The last two chapters in this book discuss ways in which you can design forms that are more intuitive and use of display elements that can help the user find their way through the documents.

Although most of the principles and guidelines discussed in this book are also discussed by other authors, what sets this book apart from other books on information design is the ample use of illustrations and examples from different genres and domains. You will want to read this book to know how you can apply the theories related to different elements to real projects, and how all the elements of information design come together when you are working on a project. Apart from this, the approach that the author adopts at evaluating an information container helps establish a method to analyze any information product ranging from a signboard to a web page.

About the book reviewed:

The Practical Guide to Information Design

Ronnie Lipton. 2007. Wiley, John & Sons, Incorporated.

[ISBN: 978-0-471-66295-2. 263 pages, including index. $42.70 USD (Hardcover).]

Available for purchase on Flipkart.

About the reviewer:

Prasanna Bidkar works at Siemens PLM in Pune as a technical writer.

Possibly related articles:

1. Applying Business Process Principles to Information Design

– Ramesh Aiyanggar

STC India organized a workshop “Introduction to Author-it” at Pune on Saturday, June 19, 2010.

This workshop was sponsored by Technowrites. Mark Trotter and Makarand Pandit were the presenters.

Mark Trotter is the Managing Director of Author-it’s newest office in Dubai. Mark has been involved with Author-it since 1999, and has used it for and managed it in various applications. He is an experienced Author-it trainer and consultant. Mark brings a wealth of knowledge to the Author-it community in the region and has recently completed a Graduate Diploma in Information Design. He is passionate about the information management field and feels that education is a life-long pursuit.

Makarand (Mak) Pandit is the managing director and chief executive officer of Technowrites Pvt. Ltd.(India). He has conducted corporate training for clients in India, Singapore, UAE, and Malaysia. Mak also works as a visiting faculty with leading institutions and Universities.  Mak is a senior member of Society for Technical Communication, and also a founder member of STC India Chapter. Mak has
served STC India chapter in various positions (including Chapter President in 2005).

The Author-it workshop was a practical one-day workshop, aimed at technical writers, to teach them the skills required to start using the Author-it enterprise authoring platform competently.

The Author-it Enterprise Authoring Platform (EAP) centralizes and streamlines the process of creating, managing and publishing formal business content.

The volume of written content within the world’s enterprises continues to explode. As the volume of content increases, so to do issues associated with searching for and finding relevant information. Today
it is not just a matter of getting information to people. It is about getting the right information, to the right people, at the right time.

Author-it EAP addresses the problems of poor knowledge sharing, duplication of content and effort, inconsistency of message and presentation, inefficient maintenance, high translation and localization costs by providing a powerful, yet easy-to-use, collaborative authoring environment that promotes reuse of content, enforces corporate standards and security, and maintains detailed audit trails.

Content in Author-it is created and managed as small reusable components, which are assembled into documents and automatically published into any number of print, help, or web formats. This results
in increased user productivity, and reduced translation costs.

During the workshop, Mark and Mak introduced the technical writers to Author-it, and helped them understand how to author, manage, publish and deliver documentation using Author-it.

Some of the topics that were covered during the workshop are as follows:
1. Overview of the workshop
2. Overview of Content Management
3. Introducing Author-it and Important Concepts
4. Installing Author-it on participant machines
5. Concept of Books & their Use
6. Objects the Powerhouse of Author-it
7. Working with Topic Objects
8. Special Objects
9. Templates and Media Objects
10. Reuse and Conditionality
11. Structured Authoring
12. Importing Objects

It was not all study, and no fun. To add some excitement to the workshop, the attendees participated in the musical chair game to compete for the lucky draw – Free Author-it license.

This game turned out to be lot of fun and there were some anxious moments too. Finally, Abhijeet Wakhare won the lucky draw and the free Author-it license. Thanks to Author-it.

The workshop came to an end with the closing remarks of Mark Trotter.

On behalf of STC India, Ramesh Aiyyangar presented the vote of thanks. He thanked the presenters, sponsors and the participants for attending the workshop and making it a success.

About the author:

Ramesh Aiyyangar is the STC City Representative for Pune.

About the illustration:

Used with permission from Nirupama Singh.

Disclaimer:

All product names, logos, and any trademarks used in the illustrations and elsewhere in this article are for identification purpose only, are the property of their owners, and their rights are acknowledged.

Possibly related articles:

1. Report: STC India Career Day & Regional Conference
2. July-August 2010 Newsletter
3. [June 2010] Learning Sessions

– Rajdeep Gupta

STC India Chapter offers technical communication professionals a platform to showcase talent and advance oneself in the field of technical communication.  The 2010 STC India Career Day and Regional Conference organized at The Gateway Hotel, Bangalore on July 17, attracted tech writing professionals at all levels – from freshers to experienced.

The objective of the conference was to reach more people who haven’t heard of technical writing as a career from universities and colleges, and technical communicators who haven’t had much exposure to STC and its activities, to build the community, and share knowledge.

STC India would like to express her gratitude to the following sponsors for their unstinting support towards the STC India events. Here are a couple of the companies, in no particular order, who had made their presence at the conference:

* Technopoint

* Yorke Communications

* Tata Consultancy Services

* VMware

* TechWritingLabs

* NetApp

* Alcatel-Lucent

* Write Concept

We had 150 registrations for the conference and a record 110 people turned up for the event. The conference witnessed technical writers, senior authors, doc managers, cms pros, usability folks and more importantly freshers from various institutes. The event was video recorded and a part of the recording is available on You Tube.

Naveen D Cruz, Bangalore City Rep and the other STC India volunteers contributed significantly towards the success of the event. The conference started with Rajdeep welcoming the gathering and inviting STC President, Michelle Cherian to deliver the inaugural speech. In her speech, Michelle highlighted the various programs and events carried out by STC India throughout the year and started the buzz for the upcoming 12th STC India Annual Conference. Click here to visit the annual conference site.

The conference witnessed speakers deliver presentations on tools, design, processes, and challenges around the technical communication space. Parallely, at the STC India hiring junction, companies  advertised job opportunities for technical writers, and collected resumes.

Hemanth was the first to deliver a presentation. Hemanth’ s solution documentation talk covered aspects like advantages of solution documents, contributors, process and challenges, and so on.

Next, Anu kept the audience engaged with her talk on “Relevance of Design for Technical Writers”. Based on her past experiences working on UX projects Anu outlined, discussed, and shared her views. Anu felt that there was a need for writers to learn about some aspects of design and usability to effectively contribute to the experience that the product offers.

Sebastian then took a leaf from Anu’ book and demonstrated how powerful it was to collaborate with SMEs for the quality of documentation.

Vasanth conducted a mock interview at the conference, which was received with aplomb. In his usual style of keeping the interviewee at toe, Vasanth grilled them on many subjects. The interviewees were from the job ranks- fresher, technical writer and senior technical writer. It was a unanimous decision of the council to award him as the best speaker for the conference.

The lunch was relished with great taste.

Prerran didn’t allow the delicious lunch to affect him and the audience a bit and proposed the Abracadabra solution. The solution in reality is a list of checklists that help writers ask the right questions, track their schedules, and avoid common risks associated with projects.

The STC India Webmaster Sridhar Machani was successful in convincing the technical communicators that they need to be familiar with building and managing web properties or risk extinction. His presentation showcased the development activities that he has been doing for the past few months for the India Chapter. Thank you Sridhar for your excellent work! Take a look here to know what I mean.

When Vinay Babu addresses a gathering, you better listen. He is one of the most accomplished speakers we have in the technical writing field today. Vinay, donning the coat of a tech writer turned manager, had tips and tricks for everyone who is in the technical writing profession and its management.

Prabhees shared his experiences on how to bag customer projects. He cited instances from a business analyst perspective on what are the qualities, constraints, aspects and so on to know for bagging customer projects.

STC India conducted a couple of contests on the day. Techwriting Labs sponsored the Essay Writing contest while NetApp sponsored the Creative Solutions contest. TCS sponsored the best speaker award while VMware sponsored the speakers’ gift vouchers. Technopoint ran a puzzle contest and gave away discounts for their training programs. The competitions Manager of STC India, Preran, dutifully took care of the competitions.

The conference provided the companies an opportunity to deliver an overview of their companies, functions, model, and their mode of operations. We hope to have more such presentations in the upcoming days. Subscribe to the STC India mailing list for details of the Chennai Regional Conference.

About the author:

Rajdeep Gupta is a writer and presently the Vice President and Sponsorship Manager for the STC India Chapter.

About the illustration:

Used with permission from Nirupama Singh.

Possibly related articles:

1. STC India Conference 2009
2. STC-India Annual Conference, December 2009
3. Report: Author-it Workshop

2011 Summit and Call for Proposals

2011 Summit will be held in Sacramento, California, during 15-18 May 2011. Call for proposals are tentatively scheduled to open 2 August and close 4 October. Keep checking the STC conference website for formal announcements.

Recorded Sessions of STC Summit 2010

If you missed the 2010 STC Summit in Dallas, you can still access all the learning by purchasing a package from SUMMIT@aClick. For $249 for members and $499 for nonmembers you can access almost all of the sessions. Know more here.

STC Offers Certificate Course

TechComm 101, presented by Leah Guren is now timed for international members, during 16 August-27 September (every Monday), at 10:00-11:30 AM GMT+3. Check here for more details.

New Assistant Manager of Community Relations

Fatima Issa has joined STC as the new assistant manager of community relations. She will be handling community relations in addition to providing administrative and financial support to STC. Read a short profile here.

Reminder: Dates for STC Recognition Programs

Nicky Bleiel, STC Director and Board liaison to the Recognitions Committee, announced the deadlines for many of STC’s recognition programs. Check here for the dates to submit applications for Associate Fellow and Fellow; Distinguished Service Awards (DCSA/DSSA/DSAS), Jay Gould Award, Ken Rainey Award, Sigma Tau Chi/Alpha Sigma; and Community Achievement Award.

STC Live Webinar Schedule

STC has scheduled webinars through November, with more to be added in the coming weeks. Visit the STC Live Web Seminar site to see the full schedule.

International Competition Award Winners Announced

The 2010 International Technical Publication Competition (ITRC) Award Winners and the International Online Communication Competition (IOCC) Award winners have been posted to the STC website here and here, respectively. See this link for more information, and keep an eye out for details on the revamped competition.

Opportunities for Advanced Learning

STC is providing one-hour webinars and multiweek Online Certificate Courses. Check the webinar page for Shake Up the Structure: Taking a Fresh Look at Information Organization, presented by Leah Guren on 28 August. Saul Carliner presents Technical Communication Manager, an Online Certificate Courses, weekly from 14 October through 18 November. Phylise Banner presents an accelerated course on Instructional Design for e-Learning from 30 November to 9 December.

Announcements compiled by Indus task force member Ashish Gupta.

Possibly related articles:

1. [June 2010] STC Announcements
2. [Feb-2010] STC Announcements
3. [Apr 2010] STC Announcements

- The STC India User Research and Usability SIG is pleased to announce three sessions on Saturday, August 28, 2010, at Misys Software Solutions (India) Private Limited, Embassy Golf Links Business Park, Off Intermediate Ring Road, Bangalore.

- The much awaited Framemaker contest is now on. STC in collaboration with Adobe, is conducting this contest. The contest closes on Sept 15, 2010. Subscribe to the STC India mailing list for more details.

- Brad Keller will present a webinar on “Easy Localization with Doc-To-Help and Microsoft SharePoint” on Aug 31, 2010. This webinar is FREE for STC members as well as non-members. Click here to register for the webinar: https://www2.gotomeeting.com/register/774341018

Announcements compiled by Indus task force member Anuj Kapoor, with inputs from the STC India chapter President and Indus advisor Michelle Cherian.

Possibly related articles:

1. [Apr 2010] STC India Announcements
2. [June 2010] STC India Announcements
3. [Apr 2010] STC Announcements

The following learning sessions/regional conferences have been conducted in the past few weeks.

Bangalore – July 17

STC India organized a Career Day and Regional Conference on at  The Gateway Hotel, Bangalore‏ on July 17, 2010. This conference included the following:

- Solution Documentation by Hemanth Basrur
- Relevance of Design for Technical Writers by Anupama Gummaraju
- Collaborating with Your SMEs and Customers to Improve the – Quality of Documentation – A walkthrough” by Sebastian
- Simulating the interview process by Vasanth V
- Abracadabra by Preran K
- Tech comm dot next by Sridhar Machani
- Doing the right things: How to be an effective manager by Vinay Babu
- Bagging Customer Projects by Prabheesh Kattambil

Delhi/NCR – July 24

STC India organized a Regional Conference at Oracle, Noida on July 24, 2010. This conference included the following:

- Workshop on Single Sourcing Using the WebWorks ePublisher Platform by Selvakumar
- Session on Power of Mentoring by Roli Sinha on behalf of Management SIG
- Session on Generating Online and Print documentation using Wiki by Suman Lata Malik and Gurpreet Singh
- Workshop on Advanced Presentation Skills & Positive Body Language by Gurpreet Singh on behalf of STC Management SIG

The following learning sessions are scheduled this month:

Hyderabad – August 28

Documentation Accessibility by Gayathri Karanam at C.A Campus

This session introduces accessibility, discusses the current challenges/barriers the end-users face, reviews the business and ethical reasons, and talks about the key considerations to keep in mind while developing accessible documentation.

Chennai – August 28

STC India is organizing a Regional Conference at Quality Inn, Sabari T Nagar in Chennai.

Compiled by Indus co-editor, and Hyderabad city representative Manoj Bokil.

Possibly related articles:

1. [June 2010] Learning Sessions
2. [Feb-2010] Learning Sessions
3. [April-2010] Learning Sessions

– Sumedh Nene

In the last issue, what I wrote about Canada was on a lighter note… this issue however, it’s getting down to business with a little more serious stuff – work related.

I have always maintained that coming to Canada has been and continues to be a humbling experience – or so it was for me as it is for so many that immigrate here. Surprisingly, many choose to come here quite oblivious to the challenges it poses. No doubt, it has its share of opportunities and potential to offer as well. Here, I am going to present some simple facts that anyone considering coming here for work – specifically us Technical Communicators – should be aware of. I’ll also walk you through a recent interview that I was at, which will give you an in-depth picture of the Canadian Technical Writer interviews. Most of what I say applies primarily to the province of Ontario, and though I don’t outright guarantee it, to an extent, the same should be applicable elsewhere in Canada as well.

Canada may not be an economy bigger than the US, but being the tenth largest in the world also makes it one of the wealthiest. As with most other G8 countries, Canada’s economy is dominated by the service industry employing approximately three quarters of Canadians (source: Wikipedia).

Let me start by saying that breaking into the job market here is not tough – it’s just an art. Those who master it, prosper; those who don’t, usually perish and head back to wherever they came from. A very popular Canadian fact is that less than 20% of the jobs ever get advertised and even less get filled that way. Over 80% of the vacancies or the hidden job market, get filled by word of mouth and employee referrals… and that is not a myth, but the raw truth. This is what makes the newcomer resource centers a starting point for most immigrant newcomers. Regardless of status, position, role or job title outside of Canada, the Job Search Workshops offered by these centers often become the tee-off point for most newcomers. These workshops help you get your bearings in a new labour market by focusing on preparing a Canadian style resume, offering interviewing tips, familiarizing you with the Canadian business English and teaching the techniques of networking for tapping into the hidden job market.

People who’ve worked in places like US and Singapore, may find the Canadian work environment not laid back, but slightly more formal and process oriented. In my one year here so far, what I’ve seen is that quality is important but process often takes precedence. I attended four interviews till now, and discussions relating to experience documenting and working within processes were ever-present.

Here’s an example of an interview I recently attended with one of the largest employers of Information Developers in the Greater Toronto Area (GTA). My interviews started in the beginning of May and four months and three rounds later, I finally got an offer. The first was a behavioral interview round. A panel of three senior managers started with a few generic and routine questions, went on to scenario based quizzing, which suddenly twisted into a rapid fire round that seemed never ending… they asked me about specific things to be aware of when writing for different cultures and had me list ten odd items in less than 25 seconds – I guess they weren’t after the content, but the amount of pressure I could withstand and get an idea of my breaking point. This round lasted exactly an hour.

For the next month and a half, I followed up – with no responses – not even a “HR will get back to you”. Then out of the blue, came the call for the next round – this time with two people – a senior manager and a senior writer on that team. I was asked in detail about process and procedure writing, dealing with clients and SMEs and several questions on information mapping, issue and time management, work prioritization and people management. It was a good thing I took my laptop and showed them samples of my work relating to every question they threw at me… if you have stuff to show, tout it – it helps to show off sometimes. This round also lasted an hour. Between this and the next round, were two more agonizing months.

This round was with the hiring manager – the person this position reports to. It was an interesting dialogue with both of us asking questions and having a conversation. We discussed our backgrounds, how bad a commute we currently have, or why we keep ourselves so composed at the workplace but show aggression and frustration at home with the people we love? I was interested in asking things I really wanted to know about that institution – structure of the doc team, types of projects, daily routine of a writer, processes followed, the team’s openness to constructive criticism and improvement. One thing to remember in Canada is: always be prepared to ask questions. Companies here generally look for thinking individuals – someone who seems genuinely interested and inquisitive, not necessarily someone who can answer all the questions but doesn’t take the effort to research and ask relevant or thought provoking questions.

One complain every newcomer to Canada has is that hiring managers insist on Canadian experience. IT is the same everywhere, C++ and Java is the same in India as it is in US or Canada then why this demand? Thinking about it though, I realized that it is not the technical content they are after, but the business etiquettes, the Canadian protocol. Embracing this fact will make settling down here a little easier. One way of getting this experience is volunteering in your career-related field. Volunteering and other unpaid jobs are considered proper work experience and mentioned in resumes as co-ops in Canada.

If anyone is considering coming to Canada and has any questions or issues, please email me and I’d be happy to address them as best I can.

About the author:

Sumedh recently expanded his India operations by opening a branch of CrackerJack WordSmiths Inc. in Toronto, Canada. He is a visiting faculty on Technical Communications at the George Brown College in Toronto, the Mentorship Manager for STC India and Events Manager for STC Toronto. You can read his article on Networking – New Age Mantra for Job Seekers published in the July 2009 Edition of the TechCraft. Sumedh can be reached at sumedh.techwriter@gmail.com.

About the illustration:

Used with permission from Mallika Yelandur.

Possibly related articles:

1. The Canadian Blend

– Anindita Basu

In my life as a technical writer, I have been handed out quite a few myths.  Some of these myths came disguised as commandments resounding with a Thou Shalt Not.  The intention, I suspect, is to lull me to passive obedience.  In this article, I will mention some of these myths, and then share with you what I think (and do) about them.

Passive voice has no place in technical writing

Before I state my position on this myth, let us recollect the definition of voice: the form of the verb that shows the relation of the subject to the action.  In other words, the voice of a sentence shows whether the subject actively took ownership of an action and did it, or was so passive as to only be the recipient of the effects of the action.

Now let us look at the structure of a very simple sentence expressed both in active and passive voice.

Active:  The installer copied the WAR files to the installation directory.

Passive: The WAR files were copied to the installation directory.

This example is a simple example and there is, actually, nothing really to prefer one voice over the other.  But, consider the following example:

License key definitions are stored in a license key file, which, by default, is named lkad.dat and located in the product installation directory. If you need to modify the list of authorised servers or users, edit the license key file with any text editor.

Is there any reason why the first sentence needs to be turned into the active voice?  Is there any reason why I want to know who is doing the storing action?  All I want to know, as a license administrator, is where the file is stored (by whoever – I don’t care) and how to edit the license definitions it contains.   Passive voice works here, and marvellously.

Upshot: When I think the doing of an action is important, I write in active voice.  When I think it doesn’t matter who or what did or caused the action so long as the action got done, I don’t spend any time changing a passive voice construction to active.

Writing must be gender neutral

With all respect to all kinds of genders on this earth, I think that’s a piece of unholy baloney.  In English, there is no grammatical gender.   But, these days, almost every Help is translated to at least one language other than English, and several of these languages have grammatical genders.   The nouns have genders, the verbs are conjugated based on the gender of the nouns, and so on.  So, what’s gender neutral in English can very well turn into a gendered phrase in a language like, say, French or Hindi.  My take is that spending anything more than 5 minutes on rephrasing an otherwise understandable and acceptable-by-usage English sentence into a  gender-neutral sentence is nothing but a waste of time.

Every list should be preceded by an introductory sentence.

The logic is, if I suddenly start a numbered list, with steps to perform a specific task, but do not introduce the list with a stem sentence, readers might be misled, confused, misinformed, etc.

Now, let’s see the following example:

1. Use one of the following methods to start the Manage Information Catalog wizard:

• From the Windows desktop, click Start > IBM DB2 > Set-up Tools > Manage Information Catalog wizard.
• At a command prompt, enter db2iccwz.

The Manage Information Catalog wizard opens.

2. Select the Migrate metadata from an existing information catalog option.

3. Enter the required information on each page of the wizard and click Finish.

It’s pretty apparent this is a procedure for migrating your data from an existing catalog to a new one, and might not really need a stem sentence that goes:

To migrate metadata from an existing information catalog:

The stem sentence adds nothing of value to the content except increasing the word count.

However, I’ve also come across procedures where, if a stem sentence were to be absent, important information would be missing.  Here’s an example:

The following steps are needed only if you overrode the default options when you installed the product.

The end result is – I leave out stem sentences if I think there’s no value add in having them.

Leave the comparatives and the adverbs alone

I am in complete agreement. Whether an application is quickly installed, easier to use, and fastest in terms of response time is a conclusion best left to the user to arrive at.  Technical writers are supposed to report facts, not hand out value judgements.

Computers (and computer applications) do not possess human characteristics, so, do not anthropomorphise them

I agree.

Wait! Did I hear someone say, ” A piece of software does guide, control, direct, <insert_verb> my actions.  Microsoft Excel lets me create spreadsheets; it does not let me create documents.    An umbrella shields me from rain; a car gets me from point A to point B.  It’s perfectly okay to anthropomorphise.”

I disagree with this line of reasoning.  When someone says, “The umbrella shields me from rain”, that’s not anthropomorphism.  That’s just someone using a verb correctly because that’s what the umbrella does – it shields people from rain. That’s an action, not a human characteristic.  Now, if the person were to say, “My brave umbrella valiantly tries to shield me from rain but fails”, now that, my friend, is anthropomorphism because the umbrella has become possessed of the human characteristic of braveness (and chivalry, perchance).

What I do?  I let my software detect conflicts and resolve them but I do not expect it to be remorseful when it crashes my desktop.

A procedure should not have more than 7 steps.

If anything takes more than 7 steps, says the stricture, break the procedure up into smaller logical pieces.  I am guessing this comes from the assumption that readers have short attention spans.  I said “guessing” because though I’ve been told there are studies that prove a decrease in comprehension levels after Step 7, I am inclined to believe if someone’s life depended on it, that person would read even War and Peace from cover to cover.

That said, I do try to keep my procedures as short as possible.  But, sometimes, the products we write for do have  procedures that cannot be fitted into the 7-step-frame.  For example, can the instructions to install a rack-mounted server system really be covered in 7 steps?

Conclusion

So, is the cow holy? Well, it depends.  When I see and understand it as holy, I am actively obedient.  At other times, I am active but in other ways.

What do you think?  What are the content myths you’ve come across and how do you respond to them?  Do comment.

About the Author:

Anindita Basu is an information developer at IBM, the company that sowed the DITA seed and continues to nurture it. She blogs at Writing Technically and can be reached through an email.

About the Illustration:

Used with permission from Nirupama Singh.

No related articles.

- Suhas Yogin & Vikrant Rai

Technical Documents don’t exist in isolation. As we are all aware, the norm of the industry is documentation sets. A documentation set contains multiple documents, each with different pagination, formats, page sizes, and any other complexities that you can add to the mix. The only factor that unifies these documents is that they are usually located in the same directory folder; at times the folder is zipped.

There is nothing inherently wrong in collecting all the documents and putting them in a folder named “documentation.” But it lacks the WOW factor. Seriously, how glamorous can a text or HTML file be? Even a PDF with multimedia content, cool 3D models, and what not?

Can we delight the user with engaging experiences while delivering technical documentation? Moreover, can we also deliver enhanced functionality and flexibility to the user? The answer is yes – PDF Portfolios using Adobe Acrobat.

What are Portfolios

A portfolio enables you to package your files into a single PDF document, with a bit of style and zing. Each file retains its own pagination and the files added to a portfolio can also be accessed individually. The portfolio provides unified navigation, search, and seamless transitions between various documents.
And yes, it also looks good and can be beautified further. Add a cover to introduce your portfolio, logos, images, text to reinforce your brand. Choose and design the layout of the portfolio using attractive presets and customizable color schemes, et al.

Unified file packaging

Package several PDF files into a single PDF. Portfolios are saved with a PDF extension and can be viewed using the free Adobe Reader. Different files such as MS Office documents, images, SWF etc can also be added to a portfolio.

Welcome screens

Design attractive Welcome screens and make your portfolio look ravishing. They are displayed when the user opens a portfolio.

Search

Search one or all files in a PDF Portfolio. You can even search non-PDF component files.

Predefined Layouts

Choose appealing layouts to suit the finicky side of you, add a dash of color.

Headers

Pick and choose, configurable headers to stylize your Welcome page.

List view

Sort component files by categories that you can add to, delete, hide, and customize. Simply click a column name to sort the list. Users can also sort files using the list view.

Publish

You are just one click away from sharing your portfolio. Email the portfolio or sign-up on Acrobat.com. Really simple.

Why portfolios are cool?

There are several more features that you can take advantage of. Following is a list of some of them that you might find useful; and help you understand why portfolios are better than combined PDFs.

Adding and deleting – Add or remove files easily, without having to find and select all the pages that originated in that file.

Previewing – Quickly preview component files without having to open them in their native applications.

Editing – Change individual files within the PDF Portfolio without affecting the other files. For example, you can renumber pages in one document without renumbering other documents in the PDF Portfolio. You can also edit non-PDF files in their native applications from within a PDF Portfolio; any changes you make are saved to the file within the PDF Portfolio.

Distribution – Share a PDF Portfolio with others and be sure that they are getting all the component parts.

Sorting -  Sort component files by categories that you can add to, delete, hide, and customize. Simply click a column name to sort the list.

Printing – Print all the PDFs in a PDF Portfolio, or selected component PDFs.

Searching – Search one or all files in a PDF Portfolio. You can even search non-PDF component files.

Incorporating other formats – Add non-PDF files to an existing PDF Portfolio without converting them to PDF.

Independence from source files – The source files of a PDF Portfolio—even existing files you add to the PDF Portfolio—are not changed when you create a PDF Portfolio. Changes you make to the component files within a PDF Portfolio do not change the original files from which you created the PDF Portfolio. You can move a PDF Portfolio anywhere on your computer or network without any risk of losing or disconnecting its components.

Reuse – Include the same file in multiple PDF Portfolios.

About the authors:

The authors can be reached on Twitter: @suhasyogin & @vikrantrai.

About the illustration:

Used with permission from Vishesh Gupta.

Disclaimer:

All product names, logos, and any trademarks used in the illustrations and elsewhere in this article are for identification purpose only, are the property of their owners, and their rights are acknowledged.

Possibly related articles:

1. The FrameMaker Five

- Sharada Palagummi

I am a technical writer and of course, I deal with technical content.  I want to create great documentation.  I know that technical knowledge and language skills are important, but I also want to use state-of the-art methodologies and authoring tools. However, my company does not find it financially advisable to invest in them.

I sighed in despair whenever I heard all those words like DITA, Author-it, Documentum, WebWorks, single-sourcing, structured authoring and so on.  Oh, what a shame, I did not even work with FrameMaker and had never even seen SnagIT.

Whenever I read or heard about the latest tools or methodologies, I was all eyes and ears; wishing that I could be using them.  Friends suggested jumping, but I was quite happy with my company: my role and my work and, yes, my package too.

One day, while watching a movie, I suddenly told myself, “Don’t whine; THINK.” Then, I did something that changed my outlook.

No more did Epic Editor bring epic images in front of my eyes; Benhur and Ten Commandments stopped bothering me.  I stopped imaging DITA as dominant and recessive genes (of course, though Darwin himself did not know much about genetics) and in the Mentos ad.  I did not feel stupid when I heard all the buzz words.

This is what I did…

I started reading about DITA, Author-it, DocBook, Documentum, single sourcing, structured authoring, information mapping and so on in detail. I tried to apply the knowledge to my scenarios.

For example, when I read about DITA, I read about specialization and inheritance, information typing, and architecture.  I concentrated on information typing; I opened a couple of recent user manuals we developed and associated terms such as concept, task, reference, message and typed phrase with the text in the manuals.  I understood the nuances of semantics of topics and semantics of content.

I opened my dictionary and looked up specialize and inherit.  The meanings “adapt or set apart (an organ or part) to serve a special function or to suit a particular way of life” in the context of biology and “derive (a quality, characteristic, or predisposition) genetically from one’s parents or ancestors” in the context of genetics helped me to understand what DITA is trying to do.

I read about the way Author-it stores all information as objects in a central database, giving authors the ability to combine and reuse objects in various ways.

Similarly, I tried to associate all the theoretical concepts with what is happening around me.

I set about typing the information, identifying the information that could be inherited, and identifying the structure and content that could be adapted.  I made the following preparations:

• Structure
  • Planned a structure for each user document type (installation guide, user manual, programmers’ reference manual etc.) we generally prepare.

Here, I remembered that most user documentation, these days, is accessed online (Apparently, DITA does not encourage the book as a basic structure!).

A user looks up a document for a specific problem and does not want to wade through information about all the hundred marvellous things the product does or how to do them.

A user wants to quickly know how to do a task without being expected to have read all the previous topics in the document – manual, help whatever.

• Represented the structures pictorially using colour codes to indicate optional and mandatory items.
• Printed an A4 size poster for each type of document depicting the recommended structure.
• Presentation
  • Created document templates for each type of document.
  • Specified styles for different types of element; created a few and modified a few others wherever I needed and I could.
• Information Typing
  • Identified the six most often used information types
  • For each type, listed the style to be used, the item it is supposed to succeed, one or two rules to remember while using it.
  • Created an A3 size poster representing the above data in a table.
• Reuse
  • Identified the content that can be reused across all the products of the company and for specific products.  Apart from content such as copyright information and document conventions, identified parts such as topics about the product that are not likely to change for quite some time, table of shortcut keys, and table of common menu options such as File, View and Edit.
  • Saved each reusable part of the content in a separate file.
  • Created an index for reusable content with the name of the file, location of the file and description of the content.
  • Access

Made all this information available on our documentation server.

This helped in improving our efficiency in documentation significantly.

I realised it might still not the same as having a tool to impose structure, reuse and consistency, and help in many other ways, and I need to look for tools.

Microsoft’s HTML Help Workshop is free.  Yes, it is really free; no strings attached.  It is compatible with HTML files created in any other application and it has a nifty decompiling tool, which produces source HTML files and images from a compiled CHM file. We have been using it for decades.

I started looking for open source software, found an unbelievably large number of them and tried out quite a few of them.

Nvu, GIMP, DoctoHelp, WordWeb and many others are robust applications.  Eclipse is an integrated documentation development environment.  There is an open source DITA authoring platform and DocBook is available as open source software.

There is plenty of scope to do a lot of things with the open source software and a few housekeeping operations.

I have a nice pin-up and am trying to drive a nail into my door.  Alas! I don’t have that beautiful, fashionable electric drill everybody seems to have.  I do not use my well-manicured nail to make a hole, ugh!  But, I settle for a hammer…

References:

http://dita.xml.org

http://xml.coverpages.org/DITA-technologyreview.pdf

http://oxforddictionaries.com

http://wiki.eclipse.org/Authoring_Eclipse_Help_Using_DocBook

http://www.author-it.com

http://www.indoition.com/online-help-authoring-tools-survey.htm

http://www.eclipse.org/articles/article.php?file=Article-Authoring-With-Eclipse/index.html

About the author:

Sharada Palagummi works with Integra Micro Systems. She has more than 23 years of experience in technical writing, localization and teaching Statistics to undergraduates. She has done courses in French, Italian, Japanese and Chinese. You can contact her at sharada.kalapatapu@gmail.com.

About the illustration:

Used with permission from Anagha Chandratrey.

No related articles.

– Michelle Cherian

On behalf of the STC India Admin Council – 2010.

It is the middle of the monsoon season, and the rain with its magical power renews the land and water supplies, thus enabling another lease of life for all of us!

At the centre of a technical communicators professional life, is technical communication, and our annual conference – which we dare to say is a time akin to the monsoon, will be here before we know it. We will have the chance to share and take the community a few more steps forward here in India by participating in this conference.

This year, the city of Delhi beckons us in November. We have received a large number of interesting topics of discussion in the form of workshops and paper proposals. We have many renowned speakers, and a huge audience of students and writers, both newbies and experienced, to meet and learn from, and take the wonder and scope of technical communication – in the form of basics, technical skills, publishing and management tools and techniques, trends in the market, and share the results of our STC India salary survey and give the audience a feel of the market for technical communicators.

For those of you looking for a change in job, there will be many companies looking for technical communicators, above all a wonderful chance to meet and network with others in the community. The workshops we have planned promise to cover a large scope of technical communication and are not restricted to technical writing alone. You will get an insight into other streams of technical communication with workshops on e-learning and corporate communications to name a few.

Our INDUS magazine and the STC portal are excellent areas where you can share your views and showcase your skills. We invite you to use the STC India Network and portal and take a little time to share/blog about what you are doing at your workplace. You will be surprised that what you feel is simple, could actually be ground breaking for someone else. Do participate in our numerous competitions and contests – the one that is running at present is our Adobe sponsored FrameMaker challenge – wonderful prizes await the lucky winners.

Let us continue to participate and grow together, build our community, and be recognized for the pivotal role that we play in our organizations. We look forward to meeting and learning and sharing with you at the 12th STC India annual conference.

About the author:

Michelle Cherian is the STC India Chapter President, and can be contacted via email.

Possibly related articles:

1. [June 2010] PrezTalk
2. [Feb-2010] Prez Talk
3. [Dec-2010] Prez Talk

VolXII, Issue 3

Conflict is an inherent feature of any relationship, and we technical writers face it every day. Luckily enough, not as much as policemen, or politicians, or even lawyers – yet enough to make us angry, and irritable. Conflicts for power in the work place, conflicts with managers and employees, conflicts with SMEs and editors, conflicts with peers who question our decisions – the forms of conflict are varied. Isn’t it surprising then, that so many of us are yet to gain any expertise on handling conflicts?

One basic technique of handling conflict is to stop before you react. When someone makes a statement you don’t agree with – take your time to react. The one who reacts fastest, is rarely a winner. Next, think of the issue from your opponent’s point of view. He might not be putting it nicely or fairly, but he may have a point. Consider if past experiences are clouding your judgment. And when you do react, be polite, never make it personal, and of course no name-calling.

In this world of conflicts, everyone is an opponent, but the solution is not mindless battle. Victory is in resolving the battle and keeping everyone satisfied, or at least not dissatisfied. Diplomacy is a virtue, which serves everyone well. We technical writers, need to equip ourselves with it. We have never had harried customers knocking on our cubicle doors demanding to know why a feature is not working as documented. But that day is not far – modern documentation is breaking down barriers between writers and customers – and very soon each and every one of us, will be talking to hundreds of customers on a daily basis. We will then have to be our own image consultant and branding expert! How then, can we afford to dismiss positive social interactions? Isn’t it necessary, that we should all learn to handle every conflict better – not in hind sight, but in real time!

Anagha Chandratrey,
On behalf of the INDUS team.

In this issue, we have an article full of tips on getting more out of your RoboHelp installation by Samartha Vashishtha and Nandini Gupta.

Kumar Dhanagopal’s article discusses the merits of user surveys to test landing pages.

Ankur Shrivastava writes about his experiences managing engineers who are technical writers.

And finally Sumedh Nene talks about his experiences getting a fresh start in Canada.

Don’t miss the STC announcements, STC India announcements, and the STC India learning sessions.

The STC India chapter President, Michelle Cherian, has a message for you.

The illustrations by Mallika Yelandur for this issue of Indus are exclusive to Indus.

If you want to write for INDUS, check out the authoring guidelines and send in your articles to the editor before the 01st of August, 2010.

Possibly related articles:

1. Jan-Feb 2010 Newsletter
2. July-August 2010 Newsletter
3. March-April 2010 Newsletter

– Michelle Cherian

As I sit here writing this note for INDUS, I realize that we are already halfway through the year! Time does fly! Our India chapter membership continues to grow slowly, and the interest and participation in the lists and Special Interest Groups as well. It is quite amazing what a small team of dedicated people can achieve with close team work and cooperation. Do make the time to help us achieve more. Do share your ideas with us on how to improve our activities.

We have begun the planning of our annual conference, taken it to Delhi this year, to try and reach out more of the technical communicators in other parts of the country who have never heard of the Society of Technical Communication and what we do. We are trying to make the conference a different type of experience for everyone including our regular attendees.

We have very active Corporate Communications and Usability Special Interest and discussion groups, and the STC India Network to conduct and store all our discussions, blog at our convenience, without having to meet in person. So please do utilize all the facilities that the portal offers you to interact and share knowledge with fellow communicators. We are constantly looking for new ways to help improve this interaction between us more and more. However, many of us will agree that though there is nothing better than face-to-face interaction, webinars and video/conferencing comes in a close second.

We encourage you to participate in the free webinars being offered by companies like Author-IT, and Adobe and we hope to bring you STC webinars soon.

Our aim is to have competitions running through the whole year and not coinciding only with the annual conference, each of these competitions will have attractive prizes, so please come forward to showcase your talent!

We also invite you to come forward to share knowledge as speakers and trainers at our learning sessions and regional conferences. The only way we can build our community is to share with one another. In our busy world, with our full-time jobs and other commitments, it isn’t easy to add something like this to an already hectic schedule. But it truly is a highly rewarding experience!

In the words of Dr. Samuel Pipim, “Why settle for Good when Better is available and BEST is achievable?” We look forward to your continued participation in all our upcoming activities.

About the author:

Michelle Cherian is the STC India Chapter President, and can be contacted via email.
On behalf of the STC India Admin Council – 2010

Possibly related articles:

1. [Aug 2010] PrezTalk
2. [June 2010] STC India Announcements
3. [June 2010] STC Announcements

- Kumar Dhanagopal

Organizations use websites for a variety of purposes: to sell products and services, to get contact information about potential customers, to convince users to subscribe to newsfeeds, and so on. Regardless of the purpose, most websites have a page that is designed to be the starting point for users—the landing page.

With the advent of powerful search engines, users reach specific pages within a website directly, bypassing the landing page. On many websites, users are guided to the page they need through a sequence of prompts designed to progressively filter the available information on the website. All of these technological advances have changed the role of the landing page from being “the” starting point for a website to just one of several starting points for users to find information. Nevertheless, the landing page continues to play a vital role in meeting the needs of the organization and its audience. Like the ToC of a book, the landing page tells users what the site contains, helps users locate the information they need, informs users about the hierarchy of information on the site, and, most importantly, can help convince users to stay on the site!

How do we test the usability of a landing page—that is, whether its meets the needs of the organization and the audience?

Usability Testing Methods

A usability test provides data about users’ experiences and reactions to specific design elements of the website. Broadly, website usability tests can be classified into two groups:

• Tests that rely on indirect user-experience input such as click-stream data and eye-tracking data—indirect because such tests use the results (clicks, navigation path, and so on) to interpret the possible user experience that resulted in the data.
• Tests that obtain direct feedback from users. This group of tests has the potential to provide reliable, qualitative usability input about user experience. Collecting data through online feedback forms, videotaping users in a lab environment, and conducting end-user surveys are a few examples of methods that provide direct data.

Advantages of End-User Surveys

An end-user survey that is planned and executed well has the following advantages:

• Provides an opportunity to choose test participants

  The survey administrator has the freedom to pick participants for the test, ensuring that the results of the survey are relevant to its purpose. In addition, usability analysts can, while analyzing the survey results, apply what they know about specific participants to ‘read between the lines’ and get more contextual meaning out of the user feedback. In other methods of collecting user-experience data, the contextual information about the user is almost nonexistent.

• Allows focused testing on specific areas

  The survey administrator can design the survey questions to focus on specific areas of usability, depending on the needs of the organization and perceived problem areas.

• Enables meaningful and relevant feedback

  Participants in end-user surveys often know how the information they provide will be used. They have the opportunity to think about their experiences before responding to the survey questions. As a result, responses to end-user surveys are likely to be well considered and balanced, when compared with responses from other usability tests.

• Ensures wide coverage of usability issues

  It is virtually impossible to come up with a perfect test that covers all the possible user experience areas. Most end-user surveys encourage participants to provide feedback on areas not covered by the questions in the survey, usually via a free-form text field in the questionnaire. This ensures that end users get an opportunity to share vital input, which, in other forms of testing might be suppressed, inadvertently or otherwise.

Disadvantages of End-User Surveys

Many of the advantages of end-user surveys discussed in the previous section can turn out to be double-edged swords.

• Sampling bias in the selection of test participants

  While end-user surveys certainly provide us the opportunity to select survey participants, this ability, if not used wisely, can render the survey unscientific.

  One of challenges in usability testing is maintaining objectivity through all the stages of the testing process: test design, execution, and results analysis. In a test that relies on indirect data (for example, click-stream data), most of the subjectivity creeps in during the results analysis stage. In a test that relies on direct data (for example, results from an end-user survey), subjectivity could be injected right at the start of the process when the survey participants are selected. In this sense, the results of end-user surveys are as subjective as the results obtained through indirect data gathering methods.

• Inconsistent quality of responses to open-ended questions

  The quality of responses to open-ended questions cannot be expected to be consistent across all the survey participants. The usability analyst needs to ‘normalize’ the survey results to account for variables such as the writing skills of the survey participants. At times, poor word choice by the survey participant can change the intended meaning of the feedback. In contrast, click-stream data and the results of eye tracking tests are of consistent quality.

• Subjectivity in designing test questions

  As with selecting survey participants, things can go wrong while selecting survey questions. Designers could deliberately influence the outcome of the survey by including specific questions, providing specific answer choices, and choosing specific words to ask the questions.

• Likelihood of low response rate

  Because end-user surveys are conducted after the user-experience event, their success depends on the willingness and desire of the participants to provide feedback. Despite the best efforts of the survey administrator to motivate participants to answer the survey questions, the response rate to an end-user survey might be poor, rendering the effort a waste.

• Not real time

  Direct user-experience data such as that generated from click-stream monitoring is recorded in real time while the user is actually experiencing the website. When users answer survey questions, they are likely to be significantly removed (time- and space-wise) from their actual user-experience situation. Consequently, answers to survey questions might not reflect real user experience.

When to Use End-User Surveys

• End-user surveys are appropriate when it is easy to identify a representative sample of users. For example, when a company that has recently deployed a new customer-relationship management application wants to find out how the sales force in the field finds the experience, it would be relatively easy for the company to pick survey participants from among its employees.
• An end-user survey is perhaps the best method for usability testing when the user population is limited. For example, when a department within a company decides to redesign its internal wiki page, the primary user group is limited to employees within the department.
• In certain cases, quantitative ‘handles’ such as click-stream data can be of limited value. For example, when the technical support department in a company wants to find out the effectiveness of the company’s customer support site on the Internet, it cannot rely solely on click-stream data, because that data does not necessarily indicate whether customers have been able to find the required solutions. In such cases, end-user surveys are more useful.
• When the need of the hour is quick decision making, an end-user survey can be the answer because it is easy to design and administer a questionnaire. Most organizations have mechanisms through which they can shortlist survey participants (say, customers) and reach them. In contrast, setting up an elaborate eye-tracking test or tuning the existing web analytics infrastructure to capture data from specific customers and for specific purposes can be a time-consuming exercise.

Suggested reading:
Kaushik, Avinash (2007). Web Analytics: An Hour a Day. Indianapolis: Wiley Publishing, Inc.
Nielsen, Jakob (2009). Top 10 Information Architecture Mistakes. Alertbox.

About the author:
Kumar works as a doc project lead at BEA Systems India, an Oracle company. He has been in the profession for 10 years. When he gets time after work and family commitments, he loves to dabble in carpentry. He is currently pursuing an MS TechComm (online) degree from the Utah State University.

About the illustration:
The image is used with permission from Mallika Yelandur.

Possibly related articles:

1. Adopting Documentation Usability Techniques to Alleviate Cognitive Friction

– Nandini Gupta and Samartha Vashishtha

In this second article in the technical communication tools series, we bring you five RoboHelp tips that will help you optimize your Help projects and generate better output.

Track the status of each topic from within RoboHelp

The Status tab of topic properties provides a comprehensive To Do list and several other options to track each topic from start to finish.

Any time you need to review the status of the project as a whole, you can generate a Topic Properties report.

Adjust Word macro settings for printed documentation

Sometimes, you may want to generate printed documentation from your RoboHelp project. Even if your final output format is AIR Help, WebHelp, or CHM, you may want to create interim printed documentation so that reviewers can easily comment on it.

RoboHelp uses macros to generate printed documentation through the Microsoft Word application installed on your computer. Therefore, before you generate printed documentation in RoboHelp, ensure that the macro security settings in Word are set to allow RoboHelp macros to run. In MS Word 2003, follow these steps to modify the settings:

1. Click Tools > Macro > Security.
2. Select Medium level of security and click OK.
3. Generate printed documentation output from RoboHTML. When prompted, choose to allow the RoboHelp macros to execute.

Unlike MS Word 2003, Word 2007 does not classify macro security settings as Very High, High, Medium, and Low. You must, therefore, allow all macros to run before you generate printed documentation. See this blog post to understand how. Once you have generated the output, you may revert to a higher security setting.

Create master TOCs with TOC placeholders

Let’s say your RoboHelp project is the single source for the policies to license a product in various countries. If you need to generate output regionwise or for any set of countries, you don’t need to create TOCs from scratch. Instead, create master TOCs from existing TOCs by using TOC placeholders. RoboHelp substitutes a TOC placeholder with actual contents in the output.

For more information about TOCs, see this Help article.

Format variables in UDV Design Editor

User-defined variables or UDVs help you create variables with specific values and use them any number of times in a RoboHelp project.

RoboHelp supports formatted UDVs.  This means that you can add images, links, and even multimedia files in a variable value. You can apply text formatting and even spell-check the value. What’s more – you can also add conditional build tags so that the variable value appears different for different outputs.

Examples of formatted variables:

• Product name and logo
• Logo with a link to the copyright page
• Logo with different images for print and online output

See this article for more information about UDVs.

Keep a self-signed and reusable certificate ready for testing AIR Help

All Adobe AIR applications need to be signed with a digital certificate and can’t be delivered without one. While your organization purchases one from a certificate authority, you can continue testing the AIR Help you created in RoboHelp with a certificate generated from within RoboHelp.

To create a certificate for internal use, follow these steps:

1. In the Single Source Layouts pod, right-click the Adobe AIR layout and select Properties.
2. On the Settings page of the Adobe AIR dialog box, click the Create button.



3. In the Create Self-Signed Digital Certificate dialog box, enter the following details:

• Publisher Name: Specify the name of the publisher (of the Help). Usually, it is the name of your company. If you are creating a Help application for another company, specify the name of your client.
• Country: Select the country of the publisher.
• Type: Select the encryption standard for the digital certificate. The 2048-RSA standard provides    stronger encryption than the 1024-RSA standard.
• Save As: Click Browse to select a folder and save the digital certificate that you created. Self-signed digital certificates are saved with a .p12 extension.

If you are just beginning to learn RoboHelp or want to know more about specific features, the RoboHelp online Help is an indispensable resource. You can also contribute to the documentation by adding tips and tricks, tutorials, troubleshooting information, or suggestions for improvement; all you need is a free Adobe.com account. Read these guidelines and start contributing right away!

About the author:
The authors work on the learning resources team at Adobe Systems. You can follow them on Twitter at http://twitter.com/nandinizg and http://twitter.com/samarthav.

About the illustration:
The image is used with permission from Mallika Yelandur.

All product names, logos, and any trademarks used in the illustrations and elsewhere in this article are for identification purpose only, are the property of their owners, and their rights are acknowledged.

Possibly related articles:

1. The FrameMaker Five
2. Ten Tips for Getting Your Reviews Done

– Sumedh Nene

Since moving to Canada just under a year ago, I must have received at least two dozen inquiries about the country: what I feel about it, why I chose this country, and the cultural differences I see between India and Canada – primarily on the work front. I was also quizzed by many on what I did to blend in and settle down here. So here are my thoughts on what I feel are important factors in not only feeling at home in a new environment, but also helping the localities embrace you and feel at ease with you.
With close to 250,000 immigrants landing here every year, Canada is huge on immigration. The demographics here are changing rapidly. A recent report by Statistics Canada (Canada’s national statistics agency) shows that by 2031, 25-28% of the total population is likely to be foreign-born. Population growth from immigration is estimated to be nearly 10% of the population, or 3.3 million people. It is also expected that by 2031, 63% of people living in Toronto (or Torontonians as they referred to locally) will be visible minorities – some immigrants, some local born.

Many immigrants that land here are skilled professionals – very highly educated with several years of experience. However, most are greeted with a number of barriers to employment and settlement. The lack of “Canadian Experience” is a newcomer’s Achilles’ heel[1]. This is apparently a huge gap, as regardless of where you worked or designations held, you have to pretty much start from scratch here. The other big frustration is probably that many foreign degrees are not recognized at-par by Canada. This renders the Bachelor’s and Master’s degrees earned overseas worthless, forcing the newcomer to continue schooling from local colleges.
Another significant factor is getting comfortable with the local colloquialisms – let’s call it “CanSpeak”, shall we? While the first two factors may be out of our control – this is something we can deal with, so here is where I’d like to linger on for a while. After several years of working in the Silicon Valley, California, I somehow expected Canada to be a spitting image[2] of the US. I mean, how different could it be? Well, I couldn’t have been further from the truth! In over 15 years of my career spanning 5 countries, I had never heard of Marketing Letters, JobConnect, Cold Calling, Networking, Co-ops, CareerBridge, Volunteering, Job Search Workshops, Mentoring and Credential Evaluations… all in the context of – YES – searching for a job! Long and tedious as the process may seem, they taught me a lot about the way of life, people and culture, the Canadian ethics and of course very local and often funny Canadian idioms and phrases.

I remember with amusement when as I started my house-hunt in Toronto not too long ago and my realtor suggested getting a home inspection done to ensure there were no skeletons in the closet. You missed the dreaded look on Archana’s face (my better half) when she heard that. We soon found out to our relief that he was just suggesting that we look at the history of the home for past damages, major repairs, and other issues. And I still laugh out loud when I remember the courier driver checking the package he was picking up from me and asked me to put my John Hancock on it. As I blankly stared at him, he quickly said “Your autograph, Sir”.
The importance of learning the local language for anyone cannot be stressed enough, because without it, communicating effectively becomes difficult. But as is obvious from the above examples, language isn’t just about vocabulary and grammar. Success in a corporate environment often depends on how your language evolves beyond the basics to understand local phrases, slang and business jargon.

Image obtained from http://www.timhortons.com/ and is a property of Tim Hortons and their owners, and their rights are acknowledged.

Canada is no exception to having its own, unique language. On no other corner of the world can double-double mean what it does here. Tim Hortons’, a local coffee chain – the Starbucks equivalent of Canada managed to get the word meaning 2 cream, 2 sugar added to the Canadian Oxford Dictionary in 2004. Pune has the famous “chaila”, The Hessisch (residents of state of Hessen in Germany) like to say “gel”, Singapore has it’s “yah lah” and here, most spoken sentences get punctuated with an “eh”! (usage: when it’s around -32 degrees C, one might say “Not exactly warm today, eh?”). Sound knowledge of such phrases can help you read between the lines. Now imagine, at my new office someone told me that the head of her department was a big mucky muck. “Well, fine. If you say so, but what could it mean”, I wondered. At the first opportunity I looked it up. Turns out that this was an old word borrowed from “Muckamuck”, meaning plenty to eat, which has since evolved to mean a person of great importance.
I’m not sure I’ll ever address anybody like that, but I am making an effort to adapt my colonial-style English to the Canadian environment, in an attempt to blend in. It not only allows me to harmonize with my new friends a little, but puts them at ease as well.
And the journey continues…

Footnotes:

[1] A phrase originating from Greek myth, Troy. The all-powerful warrior Achilles had one weak spot, his heel. When an arrow hit Achilles in his heel, he died from it. Today, it means a fatal weakness that a person has, regardless of how powerful he or she is.

[2] A spitting image of your mom or dad means that you look like that parent.

About the author:
Sumedh is a full time technical writer and a visiting faculty on Technical Communications at the George Brown College in Toronto, Canada. He is the owner of CrackerJack WordSmiths and can be reached at sumedh.techwriter@gmail.com.

About the illustration:
The image is used with permission from Mallika Yelandur.

All product names, logos, and any trademarks used in the illustrations and elsewhere in this article are for identification purpose only, are the property of their owners, and their rights are acknowledged.

Possibly related articles:

1. The Hidden Job Market of Canada

– Ankur Srivastava

Technical Writers are people – We just need to manage people.

I happened to manage a team of content writers first and then technical writers. I am using ‘happened’ in my statement as I entered into this role by chance way back in year 2000. Technical Writing was not a ‘very heard of’ word in that era. Fresh out of my college, I joined my first company as a content writer, uploading content on various publishing websites. Soon, I was assigned the task of an editor, which resulted in looking after the review work of three content writers. The role of an editor also requires a bit of people management. One needs to understand the way an author has written a document and get into his/her mind and then, edit the document. Off course, the rules of content writing also need to be applied in editing. Donning an editor’s hat actually leads you to believe that humans do commit mistakes, whether in life or content writing. The editor clearly needs to manage the technical authors (read people) to actually pass the work and get it to the final stage. The same still applies to my current responsibilities where there are engineering technical writers, required to write about the cutting edge technology. All are qualified to understand the engineering concepts as well as to understand the nitty-gritty of English language. However, as people, they still need to be assisted in moving in a directed way, as per the organization’s goals and vision. Combined together, I am referring to ‘people management’ of technical writers.

Technical Documentation as a specific skill

I am very sure that a significant percentage of world’s population has not heard of “technical documentation” as a specific skill, per se. As per Wikipedia, “In engineering, technical documentation refers to any type of documentation that describes handling, functionality, and architecture of a technical product or a product under development or use”. In general, technical documentation comprises:

• User guides
• Specifications
• Data sheets
• Patents
• Testing methods
• Release Notes
• Known Problems and Solutions
• Quality Management

The engineering industry today demands technical writers who are expert in various engineering domains such as electrical, electronics, chemical, and software, clubbed with skills related to the language. The shortage of this skill combination leads to organizations hiring technical writers from various streams ranging from science graduates to arts and commerce graduates, to medical students and finally engineers. Engineers are a complex entity as far as people management goes and technical writers with engineering degree are an interesting mix. Technical publication managers often tend to lose their way in meeting the demands of engineering writers, which are difficult to interpret and accept at the same time. For the records, the word “engineer” is derived from a Latin word “ingenium”, meaning “cleverness”. Need I say more about people management of engineering writers!

The Shoes of a Technical Writer – the Management Aspect

Managing engineering writers seems to be a complex phenomena as you need to manage two roles – engineer and technical writer, at the same time. Both these roles are very specific in themselves and their mix results in a deadly combo. A genre of people might think that if you know how to manage engineers and how to manage technical writers, you can manage engineering writers, which is actually a wrong line of thinking. If you have engineers as technical writers in your team, the good part is that you tend to become more competitive and logical, as the engineer in you enables the problem solving skill in you while the writer in you inclines you towards the creative aspect of writing. Put together, these two aspects result in a win-win situation for you as well as for the organization.

The engineering writers in your team will criticize the problem as corrective and will eventually ask you to clean-up the whole mess. If you encourage them, it is good for them and the system but then, you will need to overhaul the whole process. On the contrary, some engineers, in my opinion, will lack the creative angle, but then, Rome was not built in a day. You need to adjust to their skill and give them time to shed their core of a technocrat and learn the nuances of a creative thinker.

If you are good enough a people manager, the engineering writers in your team can do wonders for your organization but they need to be properly nurtured and nourished, keeping in view their ambitions as an engineer, and as a technical writer.

The Financial Perspective

A recent study in the U.S. ranked technical writing as the 13th best job for year 2010, ahead of a web developer, financial planner, and aerospace engineer. Income level was one of the factors in this study and the ranking has clearly defined technical writing as a better income prospect, if not the best. As is always said, one needs to be practical in his financial evaluation. In the U.S., technical writers are paid handsomely and India is also not far behind.

If you are in an engineering domain organization and you are an engineering writer, you are definitely going to be valued more as compared to a non-engineering company but not at par with the technical experts of the organization. Same message should be made clear to the team of engineering writers and transparency should be maintained (not at the salary level) but at the responsibility and role clarity level. People are smart enough to value them compared to others and if they are not, it is our duty as managers to make them smart and see life through a clear window. In my personal opinion, engineering writers rule the roost here also because of their methodical approach and belief in practical aspects than theory.

Disclaimer:

The views mentioned in this article are solely the author’s and ABSOLUTELY NOT of the organization he is currently working with. The thoughts are NOT BIASED towards technical writers who come from backgrounds other than engineering.

About the author:
Ankur Srivastava is leading the technical documentation team of the R&D division at STMicrolectronics India Pvt. Ltd., Greater NOIDA, India. He has over nine years of experience in managing content developers and technical writers. His interests include playing cricket, badminton, lawn tennis, volleyball, swimming, working out, driving, photography, quizzing, and above all, talking to his baby daughter.

About the illustration:
The image is used with permission from Mallika Yelandur.Yelandur</a>.</em>

Possibly related articles:

1. Dealing With It!
2. Do Indian Technical Writers Need Professional Courses?

The following learning sessions have been conducted in the past few weeks.

Delhi (NCR) – 22nd May, 2010

• Gurpreet Singh presented a session on Presentation Skills for Technical Writers.
• Rajeev Jain presented a session on Agile Documentation.

Bangalore – 12 June, 2010
STC India User Research and Usability SIG conducted two sessions on Saturday, June 12, 2010, at Cisco Systems India Pvt. Ltd.

• Usability – The Art of Writing – Mohan Krishnaraj, Wipro
• Usability Testing – Rajdeep Gupta, Misys

The following learning sessions are scheduled.

Delhi (NCR) – 26 June, 2010

• Alok Sharma will present a session on Technical Writing: Return on Investment (ROI).
• Harinder Sehgal will present a session on Usability in Technical Documentation.
• Amit Chandra will present a session on How to be a part of an Effective Transition to Agile-based Documentation

Comviva is sponsoring the venue for this STC Learning Session. For more information, write to Manisha Khurana.

Pune – 19 June, 2010
Mark Trotter and Makarand Pandit will present an introduction to Author-it. Registrations for this session are now closed.

Bangalore – 26 June, 2010
STC India is conducting a one-day conference on DITA. This event will include the following presentations:

• A presentation on DITA – Gyanesh Talwar, Avaya
• Designing Content Models for Reuse across Information Products – Jyoti Jandhyala, Oracle
• Leveraging DITA to help users – Ashwath Gudugunti, NetApp
• Peer review in DITA help – Mallikarjuna Prasad, NetApp
• Makeover of Information Management Systems – DITA Migration Strategy – Jyoti Jandhyala, Oracle

For more information, email Rajdeep Gupta.

Possibly related articles:

1. [April-2010] Learning Sessions
2. [Feb-2010] Learning Sessions
3. [Aug 2010] Learning Sessions

Certification for Technical Communicators
STC announced on 2 May that within the next year, certifications will be available for technical communicators in six core competency areas, namely User Analysis, Document Design, Project Management, Authoring (content creation), Delivery, and Quality assurance. On 30 April, the STC Board of Directors accepted a business case from its Certification Task Force. Currently certification will be based on assessing portfolios and work artifacts, not examinations. Click here for more details.

Online Certificate Courses from STC
STC has posted two Online Certificate Courses. The two courses already announced are:
* TechComm 101, 19 July-30 August, Presented by Leah Guren
* Technical Communication Manager, 14 October-18 November, Presented by Saul Carliner
More courses will be announced in the coming weeks. The details can be found here.

Intercom is Now Online!
The final step in the in-depth overhaul to Intercom is complete, with an online HTML version of the magazine. Months of work by the Intercom Redesign Task Force has come to fruition here. You can read the HTML, PDF, and flipbook versions, as well as purchase and read a print copy.

Upcoming webinars
The following Webinars have been announced:

• Promoting Your Career through Social Media – presented by Rich Maggiani on 23 June.
• Building Visual Explanations: Practical Advice for Writers – presented by Don Moyer on 30 June.

More information here.

Body of Knowledge Introduces “Adopt a Topic”
At the 2010 Summit, the Technical Communication Body of Knowledge (TCBoK) Task Force introduced its latest push, for populating the wiki: Adopt a Topic! Visit the TCBoK site and click on “Volunteer – Adopt a Topic.” Or if you want to jump right into it, go directly to the Adopt a Topic page!

The 2010 President’s Award Winners
Larry Kunz and Rick O’Sullivan both received the prestigious President’s Award from STC President Cindy Currie during Keynote Session at the Summit in Dallas, Texas. Read more here.

STC Publications online
The brand new website for Technical Communication is now live here! Alternatively, visit the STC website and click on the “Technical Communication Online” button to access it. The sites will be evolving constantly, so please give feedback!

2011 Elections
Interested in running for office in 2011, or know someone you think should run? See the nomination form in the April edition of Intercom.

Announcements compiled by Indus task force member Ashish Gupta.

Possibly related articles:

1. [Feb-2010] STC Announcements
2. [Aug 2010] STC Announcements
3. [June 2010] STC India Announcements

12th Annual STC India Conference: Call for Papers
Preliminary information about the 12th Annual STC India Conferrence has been updated on the STC India portal.
The call for papers is open till the end of July. For more information on how to send your proposals, click here.

STC-India logo Design Competition
The winner of the STC India logo design competition was revealed as Vikrant Rai. Vikrant wins an iPod Shuffle for his winning effort.

Technowrites-STC India Diploma Course in Technical Communication
Students graduating from the course will get a certificate with a logo of STC India on it. The first batch will be conducted in Pune, at the Technowrites premises. For more information, contact Mak Pandit.

Career Day and Regional Conference

STC India has organised a Career Day and Regional Conference in Bangalore on July 17, 2010. This conference promises opportunities for senior and junior writers, students, and hiring managers. If your company is interested in sponsoring or participating in the conference, please send an email to Rajdeep Gupta at rguptaz@gmail.com, the STC India Sponsorship Manager.

The the conference agenda and registration link for participants will be announced soon on the STC India mailing list. This mailing list is now open to non-members as well. Click here to subscribe.

Announcements compiled by Indus task force member Anuj Kapoor, with inputs from the STC India chapter President and Indus advisor Michelle Cherian.

Possibly related articles:

1. [Feb-2010] STC India Announcements
2. [Aug 2010] STC Announcements
3. [Aug 2010] STC India Announcements

Vol XII, Issue 2

We often overlook the power we have been given – by the One who doled out talent (or genes!), and the ones who gave us our jobs as writers. The power of the written word. We have used lines like the pen is mightier than the sword in school essays and elocution competitions, but I wonder if we really understand the depth of the truth that lies in that proverb.

A talent with words brings along the power of expression. An ability to express can lead to an ability to convince. Therein, my friends, lies the true power of language. Because a good idea, is no good if you cannot express it and get people to buy it. Whether you want your cook to be more punctual, or you want your boss to agree that you truly deserve that raise, you do it by finding the right things to say, at the right time, and in the right manner. You can gesticulate, but there is no use if you cannot articulate.

A good technical writer, is one who can convince the person seeking help, that there is nothing to worry about. A good technical writer simplifies the task for the user or reader. No matter what technology or medium we use, and no matter what the usability analysis dictates, we cannot dispense with words! In that case, is it not in our best interests to pursue words, and the ability to string the exact words for describing each scenario, and for encapsulating the entire matter?

We are lucky indeed – that we play with such powerful tools. But it is up to each and every writer to decide in what manner to use that power. To discuss the stubborn developer who just doesn’t understand, or to discuss a bright idea with the stubborn developer, and make him understand.

Anagha Chandratrey
On behalf of the INDUS team.

In this issue, we have Samartha Vashishtha and Anindita Basu giving us tips on using FrameMaker, and for harnessing the power of Dita respectively.

Sharada Palagummi demonstrates an editor’s job by reviewing two help topics, keeping in mind the youngsters of our community.

Shelpa Kaul reviews a wiki used for documentation and Manoj Bokil tells managers how to deal with, well, managing!

Don’t miss the STC announcements, STC India announcements, and the STC India learning sessions.

And speaking of STC India, the phase II of the portal development is on in full swing. Sridhar Machani, the STC India Web Consultant tells you more about it. As always, we have a special message for you from the STC India chapter’s Vice President, Rajdeep Gupta.

The illustrations by Mallika Yelandur for this issue of Indus are exclusive to Indus.

If you want to write for INDUS, check out the authoring guidelines and send in your articles to the editor before the 01st of June, 2010.

Possibly related articles:

1. Jan-Feb 2010 Newsletter
2. July-August 2010 Newsletter
3. May-June 2010 Newsletter

Possibly related articles:

1. [Feb-2010] STC India Announcements

– Anindita Basu

DITA is about semantic tags. This means all content must be placed within tags that explain the purpose of the content. Thus, for example, a UI element is tagged with the <uicontrol> tag (and not with <b> as we’re wont to do in HTML) and a directory location is tagged with the <filepath> location rather than a formatting tag that goes < font face = courier, size = …>. What tags can be used while wiritng in DITA is governed by its DTD. We, as writers, don’t change the DTD but write within its framework. When we write in DITA, we do not worry about formatting – how a tag is rendered in the output is governed by its stylesheets (which, again, we as writers rarely ever modify). All we worry about is whether that which we’re writing is being placed within the correct DITA tags.

To me, this was godsent because it freed me from worrying about the presentation of content and left me free to do what I like doing best – write. But when I first started writing in DITA, I stumbled a couple of times – sometimes to find the right allowable tag for my content, at other times to enhance the presentation by adding a caption or removing a link when these could not be done with whatever tag I was using. In this article, I share with you the workarounds I found for some of those early writing problems.

• To conref dissimilar elements, wrap the source text in <ph>
• To prevent all topics of a <reltable> row from linking back to each other, do not use the CTR format
• To include pretty much anything in a <step>, insert an <info>
• To preserve the formatting of a copy-pasted text snippet, use <pre>
• To have your topic show different titles in different scenarios, use <titlealts>
• To caption your images, use <fig> as container for <image>
• To have a slightly longer <shortdesc>, put it in an <abstract>

To conref dissimilar elements, wrap the source text in a <ph> tag

DITA is about content reuse. Any chunk of text, down to a single word, can be written once and called several times. There’s a rider however. Only like can call like. I cannot, for example, reuse a <step> as an <li> – if I want to reuse the text of a <step>, I can conref it only from another <step>. This becomes a bit of a hassle – say, I have written something in a <shortdesc> in a concept topic that makes perfect sense as the <context> of a task topic, how do I conref it? By using the <ph> tag.

Code at the point of the source text. Assume the file name is file1.dita

<shortdesc>
	<ph id = "textTOconref">When you set up the reporting system,
            you are setting up two separate entities: a blah and a blah blah.
            This is the text that will be reused through a conref</ph>
</shortdesc>

Code at the point of conref

<context>
	<ph conref="file1.dita#textToconref"> </ph>
</context>

A <ph> tag can be inserted almost anywhere, and, more important, can contain pretty much anything – even an image.

To prevent all topics of a relationship table linking back to each other, do not use the CTR format

The relationship tables in DITA are an extremely useful tool for maintaining, at a single point, the linking between all topics in a book. When I use relationship tables, I do not put the “See Also” links in the topics themselves but in this table where each row denotes a relationship between topics named in that row. The authoring tool I use at work is set to default to the CTR format of relationship tables, which means it’s a three-column table with a column each for concept (C), task (T), and reference (R) topics; each row in the table represents a discrete relationship and all files in a row link back to each other. So far, so good but sometimes I end up with more links than I really want.

Of the seven links, only two are needed for the topic (it’s on licenses, right?) but there are four other links, generated because those tasks needs licenses as a prerequisite (footnote). I lived with that awful clutter till I discovered another type of relationship tables – the two-column type, where one column contains source files and the other target files, and the <topicref> tags are qualified with either a sourceonly attribute or a targetonly attribute. When a <topicref> has a sourceonly attribute, a link is generated to the target topic only in the source topic; when it’s targetonly, a link is generated to the source topic only in the target topic. Thus I unclutter my topics by creating one-way links between them.

To include pretty much anything in a <step> tag, use an <info> tag

When describing procedures, sometimes it becomes necessary to include things such as pictures, code snippets, explanatory notes, and so on. But a <step> tag can contain only a <cmd> tag and then a bunch of other tags that are pretty useless for pictures, notes, and code. The workaround is to insert an <info> tag after the closing <cmd>; an <info> tag can contain pretty much anything.

<step>
	<cmd>At the command prompt, set the JAVA_HOME variable to point
             to the installation directory of the Java development kit.</cmd>
		<info>
			<codeblock>
			set JAVA_HOME=<JDK_installation_directory>\Java\jdk1.6.0_18
			</codeblock>
		</info>
</step>

Better still, an <info> tag can be placed pretty much anywhere.

To preserve the formatting of a copy-pasted text snippet, use <pre>

Because DITA is XML, anything enclosed within < > is interpreted as a tag. However, if I need to include something like this in my doc, what do I do?

<preference
	name = "the key of the preference"
	value = "the value of the preference to be set">
</preference>

I wrap the text in a <pre> tag, just like I’d have done if I were writing it in HTML. With the <pre> tag, not only can I use the angular brackets but also preserve the spaces and the line breaks.

To have your topic show different titles in different scenarios, use <titlealts>

The <title> tag of DITA has more than one use: not only does it show up as the first heading on a topic, but also as the topic heading in the Table of Contents, and in the result page of a search query. But what makes perfect sense as a topic title on the topic page that has stuff written on it might seem out of context in a search result page. Look at this picture (footnote) and tell me if the titles tell you anything at all – whether you should click-through to a topic or skip?

I use <titlealts>, with which I can specify two additional titles: a <navtitle>, which shows up in the ToC pane, and a <searchtitle>, which shows up in the search results page. I make these two titles slightly more verbose than the actual page title, so that they make sense even when seen outside the context of the page content.

<title>Installing</title>
<titlealts>
	<navtitle>Installing the small package<navtitle>
	<search>Installing the small package on Windows systems:
                High-level steps<searchtitle>
</titlealts>

In the absence of a <titlealts> tag, the title displayed in the ToC and in the search result page defaults to what’s contained in the <title> tag.

To caption your images, use <fig> as container for <image>

The easiest way to put an image in a topic is by using an <image> tag. But, according to the DITA language specification, an <image> tag cannot contain anything other than alt text. How do I caption my images? By wrapping the <image> tag in a <fig> tag, which can contain not only a <title> tag but a host of other useful ones such as <desc>, <note>, and <codeblock>.

To have a slightly longer <shortdesc>, put it in an <abstract>

The <shortdesc> element is what I use for writing the “pull text” for the topic – the text that shows up in search results and in hovertext for links, and thus is a deciding factor for user click-through to that topic. Mostly, my short descriptions contain 2-3 sentences that sum up the topic. But sometimes, just sometimes, I feel the need to write a longer short description. I’d still like to retain the shorter short description as the pull text, but what if I want to add another two sentences and want to have them all in that section itself – the first section on a page – instead of carrying the extra sentences over to the body of the topic (where they’ll probably have to reside after a <prereq> and, thus, lose all sense of connect)? In such a case, I use an <abstract> tag (footnote), like this:

<abstract>
<shortdesc>You can automatically install the adapters to an existing instance
        of WebSphere Application Server, automatically install a new
        instance of WebSphere Application Server and then automatically install
        the adapters on the new instance, or manually deploy the adapter files
        on WebSphere Application Server.</shortdesc>
If you choose the manual deployment method, after the installation is over
you must deploy the data service Web archive files to an existing WebSphere
Applicaton Server and then add the adapter plug-ins to the Web application.
These steps are not needed in the automatic installation option.
</abstract>

Footnotes

1. DTD stands for Document Type Definition. It defines what tags and tag attributes are used in a markup language, where those tags should appear, and which tags can be contained by other tags. To borrow from the musical metaphor of Hindustani classical, a DTD is like a raag’s aroh, avaroh, and permitted notes where, for example, a Pancham must always be followed by a Shudha Nishad which, in turn, can only be followed by a Shudh Dhaivat.
2. About the “Related links” example: It’s okay if I show that doc snippet as a bad example of a reltable. I wrote the doc.
3. About the search results picture page: It’s okay again. That’s my doc – my editor was very sweet while pointing out it rendered no one any help whatsoever and was next to useless.
4. The <abstract> element was introduced in DITA 1.1 but the language specifications page still does not list it. For information on the <abstract> element, click here.

About the author:

Anindita Basu is an information developer at IBM, the company that sowed the DITA seed and continues to nurture it. She blogs at Writing Technically and can be reached through an email.

About the illustration:

The image is used with permission from Mallika Yelandur.

All product names, logos, and any trademarks used in the illustrations and elsewhere in this article are for identification purpose only, are the property of their owners, and their rights are acknowledged.

Possibly related articles:

1. Writing My First DITA-Ready Topic
2. Five RoboHelp tips

– Sharada Palagummi

This article is meant for writers who are just trying to find their feet in the technical writing field. I will take a couple of excerpts from some user documentation, and will discuss them. Some points might be not acceptable and many might be missing. My purpose is simply to set off a thought process.
Remember, the most important reader of a manual or help is the user who uses the product. The product may be hardware or software. It may be a desktop product or a handheld product. The user may be a common man or a high-tech programmer. In any case, our primary duty is to this “user”.
While writing to help the user, keep 4Cs in mind: Correct, Clear, Crisp, and Consistent.

Example 1 [From the Absolute Beginners Guide to Getting Started with WordPress. This work is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License]

What I liked

• Content is very clear; no ambiguity
• Content is helpful to the user
  • Reassurance that the appearance of unwanted boxes is normal behavior
  • Explanation of the cause for it
  • Suggestion to solve it
• Content is made easy to understand
  • Use of figures to show a sample file
  • Indicators (arrows) to highlight the point

What I wished were better

• Language
  • Spelling mistake: carraige instead of carriage.
  • Punctuation:
    • W of Windows should be in upper case. Windows is the name of an operating system; W must be always in upper case.
    • Similarly, Notepad is the name of a software tool; N must be always in upper case.
    • In …formatting of the file Which will, the letter W of which should be in lower case.
    • Missing commas: For example, in To correct this open the file, I’d use a comma after this.
  • Tenses: Use of future tense instead of simple present.
    As most style guides recommend, simple present tense helps the reader understand quickly; avoid all other tenses.
  • Simplicity: Use of unnecessary words
    • This is normal. It is caused by the fact that Unix, Macintosh and PC operating systems all represent carraige returns with different codes could be written as It is because Unix, Macintosh and PC operating systems represent carriage returns with different codes or as It is because carriage return is represented differently in Unix, Macintosh and PC operating systems.
    • In This will … Which will then appear like this, the word then is not necessary.
  • Clarity: Use pronouns only if what they refer to is crystal clear. In This will correctly interpret and save the proper formatting of the file Which will then appear like this
    • What is denoted by this is not clear.
    • What is denoted by Which is not clear.
  • Correctness:
    In This will correctly interpret and save the proper formatting of the file Which will then appear like this
    • It is not the act of saving and closing that interprets correctly; it might be the Notepad software.
    • What is being done is the correct interpretation and display of the carriage returns; not the formatting of the file.
• Presentation
  • The curved yellow arrows are rather big and distracting.
  • The text mentions lack of word wrapping, but the figure fails to indicate all the text being in a single line.

Example 2 [From VideoLAN Wiki: VLC Usage. VideoLAN is an open source multimedia player and a server to stream live and on-demand video to network and the Internet.]

What I liked

• Content is clear; no ambiguity.
• Content is helpful to the user.
  • Knowledge is shared with the reader about concepts such as playlist, podcast, SAP announcement, and shoutcast.
  • Explanation of concepts and features is brief, clear, and without jargon. The purpose of the features is made clear to the readers.
  • Procedures are explained clearly with only the necessary content.
• Structure of the content: Good with a brief explanation of the feature and procedure to use it.

What I wished were better

• Language
  • Punctuation: After phrases like To add a Podcast URL and To add a Shoutcast radio listing, semicolons are missing.
  • Proofing could be more rigorous. For example, in Step 3, there is an unnecessary article, the, before the name of an option and in 5c, the word Specifying is repeated.
• Presentation
  • The screenshot lacks helpful data; the duration is zero for all the items.
  • The screenshot does not exactly correspond to the explanation.
  • There is no caption after the screenshot.
  • In Step 5, options are written as if they are sub-steps of a procedure; actually, they are not.
  • The buttons at the bottom are not explained.

What I have mentioned are very basic points. After reading this, try to find more points about these excerpts. More importantly, try to avoid such errors before you make a delivery and try to ensure you covered the good points; don’t expect your customer or boss to find these simple errors.

About the author:
Sharada Palagummi works with Integra Micro Systems. She has more than 23 years of experience in technical writing, localization and teaching Statistics to undergraduates. She has done courses in French, Italian, Japanese and Chinese. You can contact her at sharada.kalapatapu@gmail.com.

About the illustration:
The image is used with permission from Mallika Yelandur.

No related articles.

- Samartha Vashishtha

If you’re always looking for quicker ways to accomplish tasks, these FrameMaker tips are just for you!

1. Find is not just for text…

You can use the Find/Change feature in FrameMaker to look for many different kinds of objects across a book or in a document. In particular, the Find Unresolved Cross Reference option could save you hours of troubleshooting when you generate PDFs.

The following Find/Change options are worth a mention as well:

• Paragraph Tag: Search for a particular paragraph tag. For example, you can use this option to quickly browse through all Heading1 paragraphs in a document or a book.
• Any Text Inset: Search for content snippets imported by reference into the FrameMaker document or book.
• Anchored Frame: Search for graphics contained in anchored frames.

2. Track content changes across document versions

The Compare Documents feature in FrameMaker lets you create a consolidated document in which changes between versions are highlighted using inserted and deleted conditional tags. This feature is especially useful in collaborative environments that make use of a version control system.
Follow these steps in FrameMaker to compare documents:

1. Open both versions of the document.
2. In the newer version, choose File > Utilities > Compare Documents.
3. Choose whether you want to see only a summary of the changes or the consolidated document as well.

3. Import book-level variables and formats

Your FrameMaker documents may have variables that are common across all chapters in a book. Set these variables in one of the chapters and then use the File > Import > Formats to import these variables into the other chapters.

If you also plan to import paragraph format properties from this chapter, ensure that it uses all the common styles used across the book. For example, if some of the files in the book have <Heading 4> topics and the file you’re importing formats from has none, you may notice formatting (and numbering) problems in the final PDF file. In such a case, set and import paragraph formats from a file that has <Heading 4> topics.

4. Create separate paragraph formats for comments

In addition to using conditional formatting, create one or more paragraph formats for comments and internal, editorial text. Use striking formatting for these paragraph formats, so that they stand out even when the condition indicators are hidden.
For example, create a text format, AuthorQuery, to highlight critical questions that you want the reviewers to notice. Use these example attributes to format this new paragraph format:

• Bold, red, sans-serif font (if the body text is serif font such as Arial)
• 1.5 lines of vertical space above and below the paragraph

For added effect, make the paragraph cover both columns if you have a two-column layout. Further, you can set the auto-numbering for the paragraph format to display the text, “Author Query”.

5. Apply change bars selectively

Aside from going with automatic change bars, you can select text and apply change bars to it at will.

• Select the text and then press Ctrl+Shift+H to apply change bars to it.
• To remove the applied change bar, select the character, word, sentence, or paragraph and then press Ctrl+Shift+H again.

Selective change bars come especially handy when you want to proof the source or highlight specific sections for review.

6. Make change bars invisible in interim PDFs

I said five tips, right? Time for a bonus tip!
If you want to preserve change bars in the source but hide them in an interim PDF, set their color to white in the Change Bar Properties dialog box (Format > Document > Change Bars). Later, if required, you can set the change bar color again to a visible color.

If you choose to make the change bars white, ensure that you don’t have a black background for the page numbers in the header/footer. Otherwise, white change bars will be visible alongside changed page numbers in the PDF.

If you are just beginning to learn FrameMaker or want to know more about specific features, the FrameMaker online help is an indispensable resource. You can also contribute to the documentation by adding tips and tricks, tutorials, troubleshooting information, or suggestions for improvement; all you need is a free Adobe.com account. Read these guidelines and start contributing right away!

About the author:
Samartha Vashishtha works as a technical writer with Adobe Systems, Noida. In his spare time, he likes to read poetry, short stories, and food writing. You can follow him on Twitter at http://twitter.com/samarthav.

About the illustration:
The image is used with permission from Mallika Yelandur.

Possibly related articles:

1. Creating Portfolios Easily
2. Automation of Documentation Submittals via HP Quick Test Professional
3. Five RoboHelp tips

– Shelpa Kaul

Confluence is an enterprise wiki and is developed and marketed by Atlassian Software Systems.
Confluence is used for documentation by code developers and project teams starting from requirement gathering and use cases to deployment and support documentation. Also, software developers use Confluence to document the systems and guidelines.
Technical leads and project managers document best practices, scope, schedule & timelines, status, and risks related to project deliverables.

Confluence Features

Confluence is self-generated, flexible and easy to use. It is helpful in storing and collaborating information, particularly useful in an international workplace. You can edit in two modes: Rich Text and Wiki Markup. Using Rich Text is quite easy as you write in WYSIWYG (what you see is what you get). Power users can author content using Wiki Markup option.

Every aspect in Confluence can be customized; for example, you can customize the interface that includes layout, fields, navigation and colors. Also, you can use the admin preferences to select privileges and security levels.

Confluence bundles up most of the demands required by organizations and enterprises. Confluence integrates features that are perfectly suitable for multiple groups and users. It is impregnable, so confidential information remains secured. With its full-proof permission capability, you can decide who should view and edit content in a particular page, who can have access to the entire space, who can create or remove attachments and comments.

1. Confluence Wiki is not complicated as the other content management systems (CMS).
2. Every user gets to contribute or comment about a topic or on a piece of content. In this way, Confluence helps flow of communication in the team and people who are not authorized to view or edit the content can be eliminated.
3. Information on Confluence is not static; it keeps changing as and when there is a new update in the project documentation.
4. There is an option to view changes made by the users and also restore the versions, so you do not have to fear about losing information.
5. Confluence Wiki can be a repository of knowledge and documentation that develops with your growing project and organization.

Confluence Benefits

• Easy and powerful authoring tool
• Solid attachment feature
• Search is quick and in one specific location and page
• Page history can be tracked and reverting to previous version is possible
• Subscribe to Notification updates (specific to a page or entire space)
• Permission can be restricted for any page
• Content architecture – table of content, left hand or top bar navigation
• Importing excel sheet (file) is possible

User Generated Content (UGC)

Confluence is a classic example of User Generated Content (UGC), as it is mainly generated by the end users who use the content and also keep adding more content to the space.
• Mostly, the content creation is by subject matter experts and also by a technical writer in assistance with a subject matter expert.
• UGC needs to be reviewed and edited by space administrators and technical writers to avoid any wrongly placed content, language and grammar, or to make sure there are no copyright issues.
• In short, the content has be monitored and checked to ensure it meets the set standards.
• Only the project team gets permission/access to the project space. Others cannot view the project name in their Confluence Dashboard. So, the generated content can only be from the project team.
• Comparing with Online help generated using Robohelp, where one needs to install Robohelp to use the tool and update/author content. Here in Confluence, anyone who has access to the project space can update content.
• UGC in a particular project is not open to others outside the project, so there are very few concerns like copying, copyright issues. (This is in comparison to the public sites like Flickr, Wikipedia and others).
• The quality of UGC is sometimes not up to the mark when compared to the quality of documents authored by a technical/content writer. This issue needs to be corrected on regular basis to maintain project documentation standards.

Design Guidelines for Confluence-Wiki

1. Layout and navigation of content
To place the content/information according to their importance and priority, follow Jakob Nielsen’s usability theory that states that users read in the format of ‘F’ 1, 2, 3.

2. Maintain consistency and avoid cluttered appearance
Maintain consistency in navigation and look & feel of all the project spaces.
Leave considerable white space in-between the text columns. There should be good balance between volume of information and white space.

3. Minimize page scroll, almost zero scroll
Research states that only 10% users scroll beyond the first screen.

4. Tooltip for hyperlinks
This gives information to the user about content available on the next screen. These are “trigger-words” that will help the user achieve his/her goal.

5. Pop-up Windows
It allows user to view content in a new browser window. User does not lose the main page and this ensures navigation without any confusion.

6. Tabs Layout and Content Architecture
Tabs feature provides the following advantages:
• More content space for each section
• Helps user navigate the content seamlessly
Content Architecture – Categorize and modify for better content layout, understanding and readability.

Dos and Don’ts to consider as you build your Confluence space

Do
• Keep your space simple and to the point. Let two key words guide you – Categorize, Organize.
• Keep your writing clean, crisp and up-to-date. Readers will keep returning to your space.
• Keep your space uncluttered, too much information overloading keeps the readers away. Should have good balance of information and white space.
• Provide a well-structured content format that is easy and user-friendly to navigate and encourages readability.
• Use descriptive tooltips for the links to make navigation quicker and easier.
• Spell check and proofread the content in your space before publishing.
• Define acronyms and abbreviations when used for the first time.
• Show “what’s new” or “latest additions” in your space.
• Use pre-defined templates for your content. These will help you not only maintain look and feel consistency but also provide cues on the type of information you need to provide.
• Provide references to ideas or content that you have borrowed from other sources, like an article published on a website or in a book.

DON’T

• Make the readers work at finding things within your project space.
• Have too many levels of links. Not more than two or three.
• Have pages to be scrolled. Avoid scrolling as much as possible.
• Use too many graphics that take time to load.
• Use upper case text extensively.
• Write sentences in passive voice.
• Copy or use content or icons created by others without their explicit permission.

Useful Confluence Macros

Confluence macros automate a task that you need to perform frequently or on a regular basis. Tasks performed by the below mentioned macros helps users save time substantially by executing the macro instead of manually duplicating the instructions. These macros are very useful in presenting and arranging content in Confluence.

A few of them are:
1. {card} and {deck} macro – These two macros when used in combination, creates a tabbed panel which is useful in separating content and viewing different topics in the same page at one mouse click.
2. {include} macro – Includes one page within another.
3. {link-window} macro – Links to a page or URL,  that opens in a new window.
4. {align} macro – Allows you to quickly and easily set the alignment of content.
5. {noformat} macro – Used to display unformatted text on your page.
6. {column} macro – Allows you to divide the entire space into columns to manage data representation and better content architecture.
7. {section} macro – When used in conjunction with the {column} macro, helps you to create multi-column layouts.
8. {expand} macro – Used to show and hide blocks of content.
9. {toc-zone} macro – Displays table of content that depends on headings present in the page.
10. {iframe} macro – Displays a webpage within a page.
11. {anchor} macro- Creates a bookmark anchor inside the page.
12. {chart} macro – Displays a chart using data from the available table.
13. {gallery} macro – Creates a gallery of thumbnails of all the available images attached to a particular page.
14. {lozenge} macro – Inserts a graphical panel that is ideal for creating buttons and helpful in systematic representation.
15. {panel} macro – Blocks chunk of content within a panel that can be customized with color and title.
16. {rate} macro – Allows you to rate the space.

Subscribe to Daily Notification

Repeatedly checking the Confluence space to find out if there is any new or updated content can be very cumbersome.
• There is an option that will give you an update on the Confluence content changes that have unpredictable schedule.
• You will be notified through an email every midnight about the entire previous day’s changes made on the Confluence space.

Follow these steps to receive notifications on a daily basis from all the spaces you have access to:
1. Click the Preferences link on the top right corner.
2. Click the Edit Profile tab.
3. Click the Email link in the Preferences box on the menu on the left side.
4. Select the Subscribe to daily updates checkbox and click Save.

About the author:
Shelpa has 4 years of experience in the field of technical writing with Infosys Technologies Limited as a Senior Content Lead. She is zealous about contributing to her field through knowledge sharing and innovation.

About the illustration:
The image is used with permission from Mallika Yelandur.

Possibly related articles:

1. Five RoboHelp tips
2. The Value of End-User Surveys in Testing Landing-Page Usability

– Rajdeep Gupta

I am going to start off by narrating an incident, which took place with a friend of mine, who apparently fresh from abroad picked up a pressure cooker from one of the many shopping malls in Bangalore. To his ill luck the product turned out to be defective. Poor customer service added to his woes, but he was pleasantly surprised as his tweets received many responses from users citing similar experiences.

Within a few moments, he received an update from a rival dealing in pressure cookers that they would be thrilled to provide him with a brand new pressure cooker. And I said, “Wow! The Power of the Internet”.

Technology has made our lives faster and easier at the same time. We no longer wait in queues to get our work done, but simply use the internet for everything. We are unquestionably strong advocates of technology though there are few who might actually stand up and say, “Oh! I still love writing letters with a pen and paper rather than sending an email”, or “I prefer listening to a gramophone record rather than an mp3″.

But most of all Internet has gotten us to notice our time and yes it has connected us.

With the meteoric rise in demand for connectivity, the Internet has become a communication highway for millions of users. The Internet was initially restricted to military and academic institutions, but now it is a full-fledged conduit for any and all forms of information and commerce. Internet websites now provide personal, educational, political and economic resources to every corner of the planet.

Honestly, I was not aware of the potency of online advertisement till a few months back. But, today when we organize any conferences, learning sessions, and so on, we have so many mediums to network. We have the STC India portal, where you get a chance to post announcements and discuss opinions with the groups. If this is not enough and you want to reach a large number of networkers just tweet it using Twitter. Everyone is into social networking these days and there are groups centered on technical communication and so on.

I regularly use Facebook and Orkut to spread the news of the upcoming learning sessions and and have received responses from people who have never been a part of any group. Hosting events at a professional network of LinkedIn, I generate the required curiosity.

The only constant thing in life is CHANGE. Observe it from your quarters, STC India has embraced radical changes but with positive tidings all over. It is just the beginning where we have started participating, sharing, and developing assests, together which, in the longer run, would benefit technical communication.

I am confident of an exciting season ahead for STC India where there will be lots of exciting sessions on technology coming up. For the moment, I leave you with a question – will there be a day when we would say NO to technology?

About the councilman:
Rajdeep is the Vice President of the STC India administrative council. He can be reached via email.

Possibly related articles:

1. The New Network is Here

– Manoj Bokil

All of us deal with a lot of situations in life, some good, and some not so good. Peaks and valleys, crests and troughs, ebbs and flows… get the gist? Good! In my technical communication career, I have seen many Information Development departments (just like any other department in a quality organization) ride this sine wave. This sine wave brings with itself, a fair set of unique challenges that many InfoDev managers struggle to deal with, almost daily.
My attempt is to highlight a few of these critical issues along with some experiential solutions to work around these situations.

Flat headcount projections with increased workload
Oh boy! This is a tough one, isn’t it? Don’t we all hear (experience?) this ever so often and swell our hearts refrain?
Well, in this case, you have the following options:

• Negotiate with the leaders in your management chain to take contractors on board if hiring full-time employees is not an option.
• If hiring is absolutely not an option, then you need to negotiate with your management for reducing the scope of the project, functionality/features, and so on. To do this, it always helps to collect metrics to clinically demonstrate the current workload versus the no. of available resources.

Ineffective collaboration between cross-functional global teams, perceived less-ROI from the Indian team due to quality issues, and so on
Working in cross-functional global teams, especially in matrix organizations, has almost always been a challenge, hasn’t it? Understanding, respecting, and then dealing with cultural differences is critical to the success of any global team. Working across time zones is also a challenge, yes! Difficult to overcome, yet 100% achievable. Perceptions play a key role while working with remote teams, so manage them well. They cannot see you, observe your body language, and understand your intonation/tone; thus, forming [mis]perceptions is usually quick. Explain how perceptions matter and what can be done to change them, if necessary. Good leadership involves leading by example and being a good role model for the team — helping the writers who are struggling with their writing to understand and incorporate edits correctly, and so on. In my experience, I have found that peer reviews and buddy edits (before sending the docs. out to a U.S. audience) go a long way in smoothing the wrinkles, and managers can gain the trust and respect of their team. In turn, the perceived ROI from the Indian writers also goes up! All in a day’s work, eh?

Lack of monetary motivators such as hikes, bonuses, spot awards to all the employees
Well, at the end of the day, it’s all about the money, honey, ain’t it? No amount of kudos/appreciation emails, pats on your back, and so on helps reduce the bile that fuels the acid inside the stomach. Your employees come to the office with disgruntled expressions that make you feel so very err… ahem ahem! wonderful. Let’s leave it at that, shall we? So, as managers, how do we manage this situation? Well frankly, I don’t know. While this seems to be a helpless situation without the wherewithal to give everyone what they want, in management, you cannot make everyone happy, even if you want to. Golden rule, period! So, as a manager, one needs to make tough decisions and decide to go either with merit-based raises or a peanut-butter approach… Each method has its own pros and cons, and you need to take proper judgment calls on a case-by-case basis and then decide the method that works the best for you.

Setting expectations with your team and giving feedback
It is a good idea to let your team know exactly what is expected from them. Unless that is clear, there is always going to be a disconnect in what you want them to deliver and what they think they need to deliver. Having weekly staff meetings with your team and explaining things as-is really helps. Regular 1:1s help a lot. Egad! Now to the tricky part, about giving feedback: DO NOT sugarcoat feedback or mince your words while giving feedback; your team will almost always respect you for giving them straight and honest feedback. At times, as a manager, you need to be cruel to be kind, but try and give feedback that is useful and constructive. However, keep in mind that measureability is a vital part of giving feedback that is useful and constructive. So, give plenty of validated examples when you give feedback and explain how you plan to measure improved performance. Encourage your team members to have skip-level meetings with your manager; oftentimes you will find that people tend to be more direct and blunt about issues with someone who is not their direct manager, and that way, if you share a good equation with your boss, you can more effectively address team-specific issues.

About the author:
Manoj works as the Team Manager, BRM Information Development for the Comms B.U. at Oracle Corporation, Hyderabad. Please note that the thoughts expressed in the above article are purely the author’s opinions, and are in no way indicative of the views of his employers, either past or present.

About the illustration:
The image is used with permission from Mallika Yelandur.

No related articles.

The following learning sessions have been conducted in the past few weeks.

Bangalore (April 17, 2010)

• Content Development in DITA (Darwin Information Typing Architecture) – Ashwath and Prasad
• Usability Testing – Rajdeep Gupta

Hyderabad (March 20, 2010)

• Introducing MS Windows 7 – by Sameer Chhabra
• Introducing MS Office 2010 – by Sameer Chhabra

Chennai (Feb 27, 2010)

• Introduction to Instructional Design – Georgina Evangeline
• Effective Project Management Skills for
  Technical Writers – Recorded Presentation (Saravanan Manoharan)

Compiled by Indus co-editor, and Hyderabad city representative Manoj Bokil.

Possibly related articles:

1. [Feb-2010] Learning Sessions
2. [Aug 2010] Learning Sessions
3. [June 2010] Learning Sessions

STC India Salary Survey 2009

The results of the 2009 Salary Survey of Technical Communicators in India are out and you can download the report from this location.

The STC India portal

The STC India portal was recently upgraded and given a new look and new functionality. The portal continues to grow stronger with development of Phase II that is in progress.
STC India Mentorship program
The Mentorship program is well underway with the first batch of mentors and mentees hard at work.

Author-IT Webinar

STC India, in collaboration with Author-IT, offered a free webinar on Author-IT Dynamic Assistance Platform (DAP) by Paul Trotter, Founder and CEO of Author-it Software Corporation. This was also offered to STC Canada, with whom the STC India chapter plans to collaborate this year.

Announcements compiled by Indus task force member Anuj Kapoor, with inputs from the STC India chapter President and Indus advisor Michelle Cherian.

Possibly related articles:

1. [Aug 2010] STC India Announcements
2. [Apr 2010] STC Announcements
3. [Feb-2010] STC India Announcements

Preliminary Schedule Announced for STC’s 2010 Summit

STC conference website’s Live Learning Center has a preliminary schedule for the 2010 Summit, 2-5 May in Dallas, Texas. It has the full schedule of educational session. Minor edits in the schedule may be necessary. Click here for details.

New Format for News & Notes

The STC News & Notes newsletter is cleaner & simpler now. If you have any requests or suggestions, please email them to newsandnotes@stc.org.

STC Elections 2010
The STC 2010 Election opened 9 March and ended 8 April 2010. See the outcome here.

STC Carolina webinar on SEO
On Thursday, 29 April, the STC Carolina Chapter presented a GoToWebinar session from 6:30-8:00 PM EDT (GMT-4) on Search Engine Optimization (SEO). This webinar was available to STC members and nonmembers.

Share Your Thoughts on STC and National School Standards
The New York Times published an editorial about the proposed national school standards. In part, the editorial states, “The proposals are writing-intensive and vertically aligned, building in complexity each year. The goal is to develop strong reasoning skills earlier than is now customary.” What do you think STC’s role should be in this discussion? Read more, see some comments, and post your thoughts on STC’s Notebook blog here and here.

Announcements compiled by Indus task force member Ashish Gupta.

Possibly related articles:

1. [Aug 2010] STC Announcements
2. [June 2010] STC Announcements
3. [Aug 2010] STC India Announcements

Vol XII, Issue 1

Hello and welcome to a brand new avatar of INDUS! Sridhar our publisher and the STC India portal webmaster tells you more about this transition. Do make sure you leave comments and suggestions.

Other articles in this issue are:

In this edition, we have some new illustrations created exclusively for INDUS by Aditi Barve. In her own words, “Aditi doodles with a passion and her best works are produced during long meetings and boring conferences. She blogs sporadically at http://ginglyform.blogspot.com. She accepts quirky assignments and undercover missions.” Do check out her blog.

Make sure you check out the STC announcements and the long list of STC India announcements – the new council sure plans on staying busy!

The learning sessions have begun is full swing – check out the upcoming sessions.

STC India President Michelle Cherian has a special message for you.

If you want to write for INDUS, check out the authoring guidelines and send in your articles to the editor.

~ Anagha Chandratrey.
On behalf of the INDUS team.

Possibly related articles:

1. March-April 2010 Newsletter
2. July-August 2010 Newsletter
3. May-June 2010 Newsletter

- Sridhar Machani

The new Indus is an enhancement of the older version (which we still like and is available here!).  The enhancement directly matches the evolution of static HTML pages to Web 2.0 content. At the heart of the content, we still have the individual pages, or rather, articles.

What has changed?

Apart from the obvious (usability and design) and the not-so obvious (CMS-based, standards-compliant, SEO-friendly, and more) changes, with the new Indus, we can:

• Get the content where we want it and when it is published – by subscribing to RSS or email updates about new editions, articles, and comments.
• Discuss an article – by commenting on an article’s view points and provide counter-points or references.
  
• Find related articles – by following the article’s categories and tags, no matter when they were published.
• Rate an article – by voting on the article.
  
• Share articles with friends – by email, twitter, facebook, and hundreds of other ways (!).
  
  

Acknowledgments

Thanks to the STC India 2010 Admin Council and the Indus Editorial Team for being ready for the change and for all the inputs to bring the change to life. We’ve moved all Indus editions from Aug-Sep-2009 onwards to the new format. You’ll find links to the older editions on the archives page.

We hope you’ll like it. As always, please take some time to check out the new Indus and leave your feedback in the comments section.

About the author:

Sridhar Machani is a Technical Writer at Wipro Technologies. In his spare time, he doubles up as a Web design and branding consultant. He spends most of his energy at http://sridharmachani.com.

No related articles.

- Michelle Cherian

2010… We have started this year with a bang, and at the end of January we can proudly say we have a 70+ strong army of volunteers to work and bring to you our various initiatives. When you see this first issue of INDUS online, our new Web 2.0 format of INDUS is a reality, thanks to the work of our extremely talented INDUS team, uploaded on our brand new STC portal, thanks to our webmaster Sridhar Machani, and phase II of the portal will already be in progress.

Our survey tells us that Delhi is the location for our next conference, and we are counting on you to make it a success. Our aim is to take STC to as many areas of India as possible. We have a huge group of extremely enthusiastic volunteers and STC veterans who promise us that they will extend all help required to make the conference this year a success, and we do expect you guys to pitch in too. As the saying goes, “An organization is only as good as we make it!” and we are relying on our strength as a team. We do know that many of you travel on a personal budget for the conference, so it is our endeavor to bring you better quality regional conferences to give more of you an opportunity to attend an STC event closer to your home.

We are still fighting to bring down the membership fees with small wins at present, and hope to bring it down further in the days to come. We are trying our level best to return the best value to the member, and have opened up our mailing lists and groups to non-members in an effort to popularize and share knowledge with a larger spectrum of our community. We do encourage you to actively contribute in any way you can to help us be successful in these initiatives.

We have begun a series of programs such as Corporate Communications, Instructional Design, Usability and User Research, Editing, Management, and Mentoring in addition to our learning sessions and webinars. Each of these programs will have a separate mailing list, a discussion group, workshops, webinars, and training programs. We also plan regional conferences and career days in several cities. We will have competitions throughout the year, and a wide range of scholarships, education and internship programs so we can reach out to students and educate them about this wonderful profession and grow a new generation of technical communicators that are the dire need of every company today. Our veteran Mak Pandit, takes the STC India Library on for another year and adds to the scope of our activities.

We are in initial talks with the STC Toronto chapter to encourage competitions between the chapters, as well as arrange guest lectures via webinars, and collaboration in general between the two chapters. Sumedhe Nene our Mentorship manager is helping us make this a reality.

While browsing the internet the other day, I came across this poem, by M. E. Nebraska  which really emphasizes how we want to work this year… the power of working in a team and leveraging the expertise of each one of us to take our chapter forward!

NO “I” IN TEAM
- M. E. Nebraska

Of course everyone has heard the old saying “There is No ‘I’ in Team,” But who understands it? Do you?

Would you give your ALL for your team?
Would you give up time for you,
But give more to the team if it would benefit the team?
Would you lay it all on the line for your team?
Would you gladly cheer from the sidelines for your team?
Would you take the time to say positive things to every teammate?
Would you be willing to be open-minded enough
To see everyone’s point of view – your coach’s included?

The one thing that “I” can do for a team,
Is to contribute the most “I” possibly can for my teammates.
Whether that is being a leader, a supporter, a motivator,
An instigator, an inspirator – what “I” need to remember
Is that my part as a contributor helps my team the most.

When every “I” can come together as “we,”
Is when a team becomes successful.
When “I” am willing to do whatever it takes
To open my mind and see what is truly best
For my team, is when “I” become successful.
And that’s what “I” wanted in the 1st place, isn’t it?

Do you have what it takes?
Dig in.
Contribute.
Open your mind,
Play the game.
Then, you will win.

Michelle Cherian

President – STC India Chapter
On behalf of the STC India Admin Council – 2010

Possibly related articles:

1. [Dec-2010] Prez Talk
2. [June 2010] PrezTalk
3. [June 2010] STC India Announcements

- Udita Banerjee

If you walk in expecting fervent activity, you will not be disappointed. In fact, it would be a gross understatement to call the work area busy. Seemingly unconnected words shuttle across the room, across cubicles. A world where phones are ringing off their hooks, mails are pouring in, in a deluge, files are being opened and edited and re-edited as per requirements and at first glance, chaos seems to reign supreme. Everyone seems to be in a crisis. But as I wait and observe, slowly it all sinks in. Then there is an epiphany of sorts and order is literally found lurking in between the lines. People here, after all, know what they are doing, I muse. All things blend to come under one big banner of technical writing.

One has expectations of the kind of work one will be assigned. It could be the rigorous handling of technical matter or well be mere editing. Many different images flit through my mind as I am getting used to the buzz and general banter around me. Introductions are quickly made and here begins the formal path. One’s first steps into the field are carefully mentored, monitored, and measured. Pitfalls of words, grammar, punctuation and usage, which seemed so distant and inconsequential in everyday life, suddenly crop up to ensnare one. Documentation, as I soon find out, also involves speed and accuracy with skills beyond words, such as the area of technical drawings. I would tread gingerly, for there is much scope for error.

There are good days and bad; ones on which there are clearly defined requirements, sane deadlines and unanimous choices made by the team. On even better days, work is smooth, one encounters people who’d rather be here than anywhere else. Targets seem reachable and on such occasions, you may feel that your reservation about treading this path, as the new one that you chose, is a storm in a teacup. Then there come the days which epitomize the nightmares of every writer; deadlines in terms of hours, ambiguous choices, insufficient details, fallacies and disagreements.

Good practices are many. Everyone has their own, personalized methods of error proofing, proofreading, and reviewing documents. Most updates to style changes, convention alterations are broadcast efficiently and care is taken to keep documents from reflecting personal styles of writing. Every tool that is used is frequently reviewed and kept updated according to the standards of the company. Most of all that is required is predefined in the software used.

There is, however, a downside to all of that. One is kept from creativity and imagination, from coming up with new and better ways of doing things. If there has been a hurdle, it tends to remain so until someone takes the initiative to find a way to work around it. Monotony creeps in, and unless one is constantly pushing to learn more, to add value to the document, there is not much that he or she will. Complacency tends to set in, and time drags. Days on end seem to yield no satisfaction, no drive. In spite of layers of reviewing, mistakes are many, lapses are common, errors fall through the cracks, and one wonders if it wasn’t better to automate the whole process and give in to disillusionment towards the present system.

Then there is the trouble of having to be polite. Exasperating situations, incorrigible people, hierarchy, the system and the likes must be dealt with, politely; when one has to paste the smile on ones face while it is anyone’s guess what one would rather do. One has to keep working with the grand scheme of things in mind. Besides the joy of working with people who love their job and make you love yours, there is also the tedium of putting up with the opposite clan.

It is an overwhelming world; and there is much that can improved. A team should ideally be made of individuals with comparable abilities. If the variation is too much, members of the team on both sides of the spectrum find it difficult. Either it is frustrating or disheartening. However, such a utopia is hard to achieve. So, for the most part, one has to make do with the rest of the team, no matter what capabilities they possess. It is up to whoever is leading, to recognize and tap potential. Like in every other field of work, managerial skills of the leader are of utmost importance. This happens because this is a line of work with a lot of grey areas, a lot of scope for perception; there may not always be a right or wrong. Acuity and judgment play a crucial role in forming the glue that holds a team in place. A leader should be such that he has risen through the ranks, faced similar problems from random areas of work, as the ones he will be confronted with on a daily basis.

Yet there is a pattern, it is easy to fall into place, find one’s own comfort zone. It is imaginable to carve out one’s own niche with ones best skills. It seems larger than life if one thinks of the multitude of people, in terms of numbers, who are working all over the world to bring a semblance of order and harmony in the realm of communication; to make technicalities of a product readable and acceptable to everyone. It is good to be in a relatively fresh branch, where being saturated or curious; mundane or experimental is in your own hands. And if you look at it in terms of the volume of work and extent of expertise needed, a new hand is always welcome. The rocks are menacing just until one settles in, after that sailing should be smooth. To me it seems, so far, so good…

About the author:

Udita Banerjee is studying the final year of Electronics & Communication Engineering at Manipal University, Karnataka. She is also an intern with the technical documentation team at STMicroelectronics India, in Greater Noida. Her passions include creative writing, public speaking, reading and music.

This article is her take on technical writing, a month into it!

About the illustration:

No related articles.

- Mak Pandit and Gyanesh Talwar.

Time and again this subject has been discussed on various tech-writing mailing lists. We have come a long way since the profession started getting recognition. The situation has drastically changed in the last 15 years. Important changes can be listed as follows:

• The number of Indian Technical Writers has gone up multifold. The number today is estimated to be around 12,000 to 15,000. This includes freshers as well as professionals who have made a mid-career change.
• Many companies have built their own captive teams of Technical Writers in India owing to price, co-location, availability and a number of other reasons.
• The salaries of Technical Writers have been rising for a considerable part of the last 10 years (based on the Salary Surveys published by STC India Chapter in 2003, 2005, 2007, and 2008). Though the 2008 survey does show marginal reduction or flattening.
• The expectations from Technical Writers have increased. One can cite many reasons for this, including changes in product, changes in technology, reduction in time to market, changes in documentation processes, availability of better tools, and so on.

Growth has its own challenges and issues. If these issues are not addressed, long term success is not possible. We tried to look at many questions associated with this unprecedented growth in a number of writers.

• Are the Technical Writing Managers really happy with their team members? Do they see any improvement areas?
• Are writers able to work to their level of satisfaction? Do they feel that they need to improve and learn something?
• Are the various private courses really adding value? Is the industry expecting improved courses? What change is it expecting?
• Is there any scope of means to standardize the various courses and draw some guidelines to ensure value?
• Is there any scope for Western Universities to start offering courses in India (possibly through distance learning mode)?

The authors got interested in these questions and then decided to research the market. After carefully studying the various areas that can be touched upon, we identified performance and the need of systematic Technical Writing education as the focus for our research. We prepared two surveys and then hosted them on SurveyMonkey.com for 50 days. The first survey was for Technical Writing Managers (Hiring Managers) and the second was for Technical Writers. The first survey was completed by 14 participants whereas the second survey was completed by 185 participants.

The results of these surveys were first made public during the STC India 2009 Bangalore conference. In the same session we also hosted a debate about “Whether Indian Technical Writers need degrees from Western universities?”

In this article we will try to critically look at the survey results and try to comment on some of the findings. The complete survey results can be downloaded from here.

Key readings from the Hiring Manager’s survey

First, let’s look at some of the points of the Hiring Manager’s survey.

Key readings from the Technical Writer’s survey

Now let’s talk about some of the points from the Technical Writers’ survey.

The authors are aware that the survey results can be interpreted in many ways and they can lead to many interesting conclusions. Hence many of the points made above are debatable. We welcome feedback, comments, and suggestions.

We encourage the readers to study the complete survey results. The files can be downloaded from here.

About the authors:

Makarand Pandit and Gyanesh Talwar can be contacted at makarand.pandit@gmail.com and gyanesh.talwar@gmail.com.

About the illustration:

The image is used by permission from Aditi Barve.

No related articles.

STC India chapter announces the launch 3 new Special Interest Groups – The Management SIG, the Corporate Communications SIG and the Usability SIG.

The Management SIG and program supports its members in managing technical communication groups, and in developing the skills needed to be an effective manager.

Corporate Communications SIG will have a training program starting in March for 15 participants.

Instructional Design and Editing SIGs are in the works and will be launched soon.

Makarand Pandit gets the Distinguished Chapter Service Award from STC, US. The award citation applauds his contribution in the following words: For leadership in establishing the India chapter and for sustained enthusiastic contributions to the India chapter and the STC global community.

A survey was conducted to identify the venue for the 2010 STC India Annual Conference. Delhi will host the conference this year. Promila Chitkara is the Program Manager.

Meenakshi Khanna of the STC India chapter has been elected to the Usability and User Experience Group office for the year 2010.

The competitions team is going to have competitions through the year. The first one will be announced soon and will be for redesigning the STC logo. Join the STC India mailing list to stay updated.

Makarand Pandit will continue to operate the STC India library in Pune.

The scholarship program is ready to launch and is looking forward to your inputs to reach a wider audience of students and aspiring tech writers. Write to Manju Shreshta or Susan Alexander with your suggestion and questions.

Nibu Thomas and Rajdeep Gupta of the STC India chapter won recovery packages awarded by STC.

Links:

• STC India website
• STC India mailing list
• STC India Conference Delegates mailing list
• Twitter
• LinkedIn
• Facebook

Subscribe to INDUS

• Receive new issues in your mailbox. Register here.
• Use the RSS feed for Articles.

Possibly related articles:

1. [June 2010] STC India Announcements
2. [Dec-2010] STC India Announcements
3. [Aug 2010] STC India Announcements

Intercom, Technical Communication Now Online-Only

Starting with the January edition of Intercom and the February edition of Technical Communication, both publications will be primarily in an online format. Free online access in a variety of PDF versions will be available immediately, with a web-based version available for Technical Communication starting in February and Intercom in March. Members can elect to add on a print subscription when renewing their membership. The cost is $30 for Intercom and $75 for Technical Communication.

“Technical Writer” Officially a Distinct Profession, per US Government

The US Department of Labor’s Bureau of Labor Statistics (BLS) released its newest Occupational Outlook Handbook (OOH) in December and, as STC announced was coming in April, “Technical Writer” has its own chapter for the very first time. This follows a three-year effort by STC to convince BLS of the need for such a change.

Click here to read or download the full STC press release, with quotes, a bit of history, and some comparison figures. Click here to review the Handbook’s new chapter for Technical Writers.

STC Class of 2010 Fellows and Associate Fellows Announced

STC is pleased to announce that 24 distinguished members have been named Fellows and Associate Fellows of the Society. They will be recognized at the Honors Banquet at the 2010 STC Summit in Dallas this year. See the full list on the STC Notebook blog.

STC Announces Online Certificate Courses

STC is offering online courses where participants can earn a certificate. The courses are divided into 90-minute sessions and presented live online over several weeks. To obtain the certificate, participants must log in for each of the sessions.

The current course offerings include Business, Management, and Office Skills, presented by Jack Molisani; Minimalist Writing, presented by Bernard Aschwanden; TechComm 101, presented by Leah Guren; and Topic-Based Authoring, presented by Sharon Burton. For the full schedule, details of the courses, and to register, click here.

Possibly related articles:

1. [June 2010] STC Announcements
2. [Aug 2010] STC Announcements
3. [Dec-2010] STC Announcements

- Rajdeep Gupta

In the years to come they will say great wine must age like STC India conferences. There is a sense of excitement as you uncork another bottle. Over the last 11 years, the sparks seem to be flying high, higher and it seems it will reach the highest pinnacle in some time, if not already. A conference, with all its grandeur and colors, is not just a ‘conference’ anymore, but gets transformed itself into a carnival. A carnival, which witnessed knowledge transforming into valuable assets, and experienced and not-so-experienced writers flocking together to share and learn new things. They do all this but with fun all along the way.

But, the question is how do you award a conference the tag of ’success’ or ‘failure’? Is there a need to categorize it as successful? What are the metrics for evaluating the success of a conference? There may be many and it may differ from person to person, but from my perspective, I would keep at the top ‘quality content topics specific to domains and catering to the various sections of the technical writing fraternity’. The 11th Annual Conference provided something for everyone, and most importantly, people had the options to select the topic sessions based on their medium of work experience and likeness. The pre-conference learning sessions illustrates my point – for technical writers had the option of attending sessions on editing to tools, and project managers and program managers had workshops on document program management and Zen workshops!

Though STC India organizes learning sessions and workshops all through the year, there are always folk who miss attending those events. Important topics on Dita, localization, internalization, and so on are again presented in these conferences in a detailed manner, so that attendees get another chance to make the most out of it. Feedback is solicited during the conferences, and not just trashed. This feedback is taken seriously, and the results are showcased in the next conferences. For example: the feedback I had during the 2008 conference in Pune was addressed and made the conference a huge success.

Every year the STC India conference witnesses a big turnout – not only the first timers to the event, but also people who are conference regulars. It means that the previous conferences have been quite a hit with the people and they see value in attending the conferences.

Every year, STC India arranges for a panel discussion with eminent personalities from the field speaking to the gathering. The discussion facilitates the following:

• Define and communicate the value of the profession of technical communication.
• Improve the practice of technical communication globally.

STC India conferences advance the theory and practice of technical communication across all user abilities and media so that both businesses and customers benefit from safe, appropriate, and effective use of products, information, and services. I have been attending the conferences for the last four years, and every time I have learnt something new that I can add to my resume and boost my professional development.

About the author:

Rajdeep Gupta is a writer for the last 5 years and is presently working with Misys. He is presently the Vice President of the India Chapter of STC and the Assistant Organizer of the Bangalore Technical Writers Meetup Group. He loves quizzing and is an avid blogger.

About the illustration:

Possibly related articles:

1. STC-India Annual Conference, December 2009
2. Report: STC India Career Day & Regional Conference
3. [Dec-2010] Prez Talk

Following learning sessions were conducted since the beginning of 2010.

Hyderabad (February 20, 2010)

• ASD-STE Simplified Technical English – A language standard for global use — by Rama Nagalla

Following learning sessions have been announced:

Bangalore (February 27, 2010)

• Script Writing for Technical Writers — by Surag Ramachandran
• Effective Project Management Skills for Technical Writers — by Rajdeep Gupta (recorded presentation)

Delhi/NCR (February 27, 2010)

• Managing Last Minute Changes — by Rajeev Jain
• Effective Presentation Skills for Technical Writers — by Gurpreet Singh

Mumbai (March 20, 2010)

• Introduction to DITA — by Aruna Panangipally

Possibly related articles:

1. [June 2010] Learning Sessions
2. [April-2010] Learning Sessions
3. [Aug 2010] Learning Sessions

A coffee table write-up for a Subject Matter Expert

- Deepa Gopalakrishnan

I am trying to finish that last section in my document. After the eighth revision of a segment of text over the past releases, someone in the team thought that the following piece of input would help me seal the document for the product release next week.

When you analyze the cycle time of one object the aggregation rule used is average which provides the right values for the user signing off on many objects. I immediately thought of: Betty bought a bit of butter, the butter was bitter; Betty bought some better butter to make the bitter butter better.

This may be a correct sentence, but it does not make sense to me when I am sincerely attempting to chase a release timeline. The aforementioned, (seemingly) pointless piece of supposedly sensible text (You didn’t think, I would be affected so much by the tongue twister run-on sentence, did you?) is available as a reliable live document somewhere on the Internet. I have edited  the original text to the less-confusing tongue-twister that you just read, for this article.

This is not the first time I received a pointless piece of input from the development team. Every time, I have had to take help to resolve the input issues and then proceed with my work on it. It makes me think that there is something missing; else no one would send such seemingly pointless input.

A little introspection and a rewind of sequences from my years of experience as a technical writer, revealed a patterned behavior in most developers. The basic fact that some developers have no idea about what inputs to give and what to expect of a user document is the primary cause of such inputs.

Other causes as I see are:

• Excess information
• Insufficient information
• Disparate information
• Lack of clarity
• Inability to explain
• Inability to communicate

We, as writers could help the developers or the Subject Matter Experts (SME) help us better by letting them know what we expect during a Knowledge Transfer (KT) session.

Let’s start off with a basic definition of Knowledge Transfer. The SME explains the concept to the writer. This is called Knowledge Transfer.

The popular modes of a KT are as follows:

• Discussion
• Write-up

Discussion mode

In this mode of KT, the writer meets the SME and discusses the new feature or update that has gone into the product. We must ensure that our SMEs know the following basics before they start off with the project. This section is addressed to the SME.

1. Fix appointments for the KT.
2. Schedule your session.
3. Circulate the related documents if any, prior to the KT session.
4. Be available at the appointed hour for the discussion.
5. Understand the purpose of the document.
6. Be ready to answer doubts.
7. Set aside time in your calendar for the review of the document.

Don’ts

1. Do not schedule KTs when you have an important meeting coming up. You may not be able to devote your mind to the KT completely.
2. Do not explain more than you or the writer can handle at a time. The topic may not be covered exhaustively.
3. Do not force your mind to think of the subject matter when it is busy with other thoughts. You may lose focus on important points.

Nice to know

1. Capacity to understand differs from person to person.
2. Your state of mind on the date of discussion drives your discussion.
3. It is perfectly acceptable to postpone the appointment when you are not clear about the concept.

Write-up Mode

In this mode of KT, the writer receives inputs about a topic as document attachments, emails, and web reference links. We must ensure that our SMEs who send such inputs, know the following basics before they click that ‘Send’ button. This section is addressed to the SME.

Dos

1. Always verify if the material makes sense to you.
2. In your email to the writer, specify if the material is elaborate or just about right, as you see it.
3. If you send a segment of text taken from an existing document as input, specify the source of the material.
4. Verify if you are sending material taken from the latest version of the reference document. For example, if you are referring a document written in 2004, and the next update of the document was written in 2008, then the 2004 reference may be incorrect.
5. Allot time to review the content that is rephrased or collated from the segment of text that you send.
6. Discuss your written input if need be.

Don’ts

1. Do not expect a copy-paste from the write-up you sent.
2. Do not write all you know about the subject.
3. Do not deviate from the purpose of the write-up.
4. Do not give numerous references to other documents for a given segment of text.
5. Do not give ambiguous statements as inputs.

Nice to know

1. The input that you give may be incorrect.
2. You may miss out an important point.
3. Your writer may understand a written input differently from its intended context and meaning.
4. No document is perfect; so is your input.

You can give the following guidelines to the SME to provide inputs or ensure that you have answers to all these points before you start writing your content.

Overview

General idea about the subject of discussion.

Context

Background of the topic and its importance.

Illustration

Examples, illustrations, diagrams, or screenshots.

Setting

Related prerequisites such as settings or parameters.

Key Points

• Definitions
• Field explanations
• Steps or procedures
• Alternate methods
• Possible errors
• Important notes
• Best Practices
• Other points

Impact Zones

Related areas of impact

Conclusion

As technical writers, if we are able to convey these points to the Subject Matter Experts, then we can minimize last minute hassles related to Knowledge Transfer and help ourselves do a better job.

About the author:

Deepa Gopalakrishnan is an engineer and holds a senior technical writer’s position in Oracle India, Bangalore. She has 6 years of technical writing experience in product development companies and most of her work experience involves technical writing for application software.

Deepa writes about technical writing at Knol and blogs for leisure as dewdropdeepa on BlogSpot. You can contact her at twindeepa@gmail.com.

Possibly related articles:

1. From Information Development to Knowledge Development

- Robert Raymond

In the US, many new houses are built with fences separating “your” space from “my” space. These fences are typically made from shabby material, to keep the prices down, and routinely fall down in about 10 years. A few weeks back, a rather strong storm ripped its way through my town and took a portion of my fence with it. The 16-foot gap opened onto a large open space–rare for where I live, but that open space is one reason I bought this particular house.

But I have a 16-foot gap in my fence, which diminishes the structural integrity of the entire remaining 44 feet. As much as I enjoy the view, and as I write this I am sitting in my home office, enjoying it, not fixing the fence is not an option.

So I am left with two options: fix the portion that fell down, or fix the entire fence. And here is where the juggling act begins. I can fix the portion that fell–I can patch the fence–for $500. Or I can fix the entire fence for $1250. Simple math tells me that I’m getting the entire fence for about $21 a foot. I’m getting the patch for about $31 a foot. If I patch, I “save” almost $750. But I know that the remainder of the fence will eventually fall down. But when will it fall–next winter? The winter after? Maybe, if I’m lucky, it won’t fall at all while I still own the house. But the fence is 12 years old, and shabby, and constant patching will eventually cost more than replacing the whole thing right now. And if I “constantly patch,” some portions of the fence will be old, some not so old, some new…

Oh me oh my, what to do…

This is a decision doc managers need to make all the time: balance savings today against expenses tomorrow; balance constantly patching a doc with tearing the whole thing down and starting anew. My solution to fixing my fence was the exact same I would have taken to patching a doc.

There comes a time in the life of a doc when the manager needs to take the position that the doc in its current form—with patch upon patch and even patches being patched–is no longer serving the needs of the reader and is serving only the needs of the company producing it. I have docs in my possession that thankfully no longer refer to the name of the company that we were before being acquired, but they still retain multiple forms of the name of the products that were acquired. And multiple forms of the names of the other docs in the suite. And this shabbiness is all because we are tasked with adding content.

Let me return to my fence. Did I mention that my sink has a leak? Or that my car has a “slight” oil leak? I could opt to patch all three, but I dare say that a patched leak in my sink will eventually rot the wood that supports it, resulting in an even bigger repair bill. And the “slight” oil leak will become a big one requiring a new motor. But for today, I will save money. And I will forget about the problem because so many other little issues require patches.

I fixed the entire fence. I’ll miss seeing Abby in her full glory, and I’m sure she’ll miss coming by and getting an easy rub on her nose. But I have unburdened myself patching the fence’s patches. At least for the next 10 years.

BTW, this is Abby, and then, there’s the broken fence….

About the author:

Robert Raymond works as the Sr. Editor with the Oracle Communications group at Oracle Corporation.

About the illustration:

No related articles.

- Anindita Basu

What if my Help was not at all like the Help as we usually see it?

What if every menu option had a tiny Help next to it? So every time I hover my mouse over it, it tells me stuff like “If you click Open, your currently open catalog is automatically closed and unsaved changes are lost. We don’t multitask”.

What if there was no ToC? Every time I look at a tree with branches, shoots, and shootlets, my eyes glaze over and I just holler for a friend to come help me. I’d much rather look at a clean, white-spaced page that has bullet points that go 1, 2, 3. No left pane, no right pane. What if, instead of a tree of topics, I am shown only one topic? Like it happens when I click-through a Google search link? The topic that I reached by clicking the tiny Help button on the options on the menu bar?

What if every Help topic helps me orient myself? I am lost, I am asking for directions, and I’d like to know which direction is North (there’s no sun and it’s a cloudy night, so I don’t know).What if every page had a You-Are-Here. Now that there’s no ToC, and I am reading a Help topic, it might sometimes help if I looked a little bit to the left and right and read some more. Something like, “You are reading about installing the licenses. Before this, you must’ve got your licenses. After this, you’ll be configuring the client systems” in a clickable flow-diagram.

What if all UI fields had examples. When the computer throws a wizard page at me, with fields to fill up, I am never sure if what I type in is the correct information. Can “Location” be a remote one too, with http:// and all, or is it just a local drive. I don’t like clicking that tiny question mark next to the field only to be told “It’s MM/DD/YY stupid, not DD/MM”. What if every field had an example there for me to look at and exclaim “Ah, I see!”

What if my search was tailor-made for my task? So, now that the question mark next to the UI field need not tell me what to fill up in the fields, what will it do? What if it opens a page for me that shows the results of a predefined search – a search based on the UI screen I was at (and related to the task I was doing) when I clicked the question mark?

What if the UI had embedded cheat sheets? Instead of ClickAndDo or SeeAndDo tutorials (which are fun to make, by the way), what if, when I am unsure of what to do, instead of having to read the Help or watch a video, there’s a cheat sheet that guides me along (thus assuring me I won’t mess up the system and cause the computer to come apart at its screws).

What if I had on-the-spot troubleshooting. What if, instead of an error message telling me what went wrong, there’s something that helps me correct the error? Why not pop up a wizard with which I can do that which should have been done in the first instance?

What if wishes were horses? Why, I’d gallop along on my tasks with nary a roadblock in sight.

About the author:

Anindita Basu is a technical writer with the Rational Software lab of IBM. She can be reached through ab.techwriter@gmail.com.

About the illustration:

No related articles.

Vol XI, Issue 6

In this last issue from the current INDUS team, we have:

• Urmi Roy showing how to apply business principles to information design
• Subhajit Sengupta talking about humanising localization
• Samartha Vashishtha showing the hats he wears

You can also see the STC announcements and STC-India announcements.

And, as always, the President has a special message for you.

- Anindita Basu, editor

Possibly related articles:

1. Oct-Nov 2009 Newsletter
2. Aug-Sep 2009 Newsletter
3. March-April 2010 Newsletter

- Samartha Vashishtha discusses the balance between technical and creative writing

When you were little, what did you want to be when you grew up?

I wanted to be a lot of things at different points in time. As a kid, growing up on Russian books on cosmonautics, I wanted to be an astronaut. I am sure a lot of kids want to be astronauts even today. That is the closest you can come to being Superman!

When I was 10 or so, I discovered I had some musical talent and wanted to be a professional singer. I trained in classical music for six years before the rigors of academics began to take their toll. By the time I was in college, I was pursuing a “normal” engineering career. Destiny had different plans.

What did you study to become?

I studied to become an electronics and communications engineer. In particular, I enjoyed VHDL and assembly-language programming in college. In my final semester, I was placed as a communications engineer with a leading telecom firm. As things would turn out, I never joined them.

What are you now? What do you work as and where?

I don’t think I am everything yet that I’ll eventually turn out to be!

I began my career as an editor for the LINUX For You magazine. As a student, I was inspired by the open source software world and contributed a few articles to LFY. As I approached the end of my B Tech degree, I was offered a job at LFY. Since writing had always been a passion for me, I jumped at the opportunity.

The transition to “core” technical writing happened a year later when I joined a networking technologies startup. Later, I worked for HCL Technologies, where, besides regular technical writing deliverables, I authored research papers and whitepapers as a founding member of the HCL Research group.

I currently work as a technical writer with Adobe Systems.

What do you do in your spare time?

I write and translate poetry. Poetry has been by my side for as long as I can remember. My grandfather and father wrote poetry in Hindi, so as a kid, I wanted to emulate them. I wrote poetry in English during my teenage years and had some success publishing my poems in reputed magazines. Most notably, I contributed to Chandrabhaga edited by Jayanta Mahapatra, and Indian Literature, published by the Sahitya Akademi, on several occasions. Eventually, I came out with two books of poems—Anhadnad (2000) and Shadows Don’t Live In Walls (2004), which were well-received by readers and critics.

As I began to write “professionally” in English, for some strange reason, I shifted to Hindi as my language of poetic expression. The transition was long overdue in any case. Creative writing, I think, is more fruitful in one’s native language. Over the past few years, I have contributed to some influential literary magazines in Hindi. Right now, I am working on my first book of Hindi poems, tentatively titled Smritiyon Mein Baaki Hai Ujaas.

I also translate from Hindi and Punjabi to English and the other way round. In 2007, I published a translation of the path-breaking long Hindi poem Luqman Ali by Soumitra Mohan. Translating Luqman Ali has been the most challenging assignment of my brief literary career.

After several failed attempts, I have resigned to the fact that my brain is not wired densely enough to write prose!

Are you telling us you are a non-creative writer by day and a creative writer by night?

I think the notion that technical writing is uncreative is inherently flawed. All the positions I have held so far had ample room for creativity. In fact, the changing face of the profession demands that technical writers juggle creatively between multiple roles—community moderator, social media expert, astute communicator, and of course, documentation author.

The shift to the community model of Help has already gained momentum at my workplace. We are getting in touch with expert users of Adobe products and encouraging them to add value to documentation. The results so far have been very enlightening. See this introduction.

I believe all companies will eventually wake up to this new model of documentation, revamping the role of the technical writer in the process. So, if technical writers are not finding enough ways already to channelize their creative energy at work, it won’t be long before they do!

Do you feel balancing technical writing and poetry is a dichotomy? How easy do you think is it to keep these two styles apart (or do they keep merging and you consciously have to segregate them)?

Poetry demands its own time and space. Whatever the profession, some poems always drift unwritten amid the exigencies of work. That is true for any writer. As the famous Urdu poet Faiz aptly put it: tujhse bhi dilkash hain gham rozgaar ke.

Apart from that, I don’t struggle significantly balancing technical writing and poetry. Technical writing is work—it is less spontaneous, more structured, and has to be delivered on time. Writing poetry is a long-drawn process. A poem keeps simmering in the depths of the mind for weeks, even months. Then suddenly, all you need to do is to pen it down. That may even be in the middle of a hectic workday. Penning the poem down is just the mechanical culmination; the poem has already been lived.

Also, I don’t think any good poet can be content just writing poetry. The insight for good poetry (or literature, for the matter) comes from everyday struggles and frustration. Life is inescapable.

Given a choice (assuming your financial needs are taken care of), what would you be and why?

That is a big if. I think I would still be writing for a significant portion of my time. I enjoy my career as a technical writer immensely. I think I’d continue to be a technical writer—a more finicky one!

Of course, if I were to suddenly turn a billionaire, I’d have little choice but to spend my time managing the money! “Letters to Shareholders” don’t (or rather shouldn’t) count as creative writing, should they?

Do you blog? Are some of your writings accessible online?

I (rather badly) maintain an online anthology of my writings at http://samartha.info. My creative blog in Hindi is at http://samarthav.blogspot.com.

In addition, I blog about all things Adobe at http://blogs.adobe.com/samartha. I am also active on Twitter.

No related articles.

- Subhajit Sengupta

Human personality is the sum total of the ways in which an individual reacts to and interacts with others. We all inherit a certain type of personality that helps us build our unique adjustment to the environment. The measurable traits that we exhibit through the interaction are quantified and categorized in various personality determinants.

Researchers have used these parameters to analyze personality and have developed many personality assessment tools. The Big Five Personality model, with its five factors, is one of those assessment tools that has gained popularity. Through this article, we will try to establish a link between this model and a localized help document, and gain some leaning through this association.

The five factors of personality are emotional stability, extraversion, openness, agreeableness, and conscientiousness.  Now, let us examine the five traits of this model from the point of view of localization.

1. Emotional Stability

Emotional stability is one of the most powerful personality dimensions that has a deep-rooted relationship with job performance. Any localized content that provides greater satisfaction through the right mix of quality information and local flavor can help customers understand and use features of a product or service efficiently, and, as a result, lead them to higher satisfaction and lower stress level. So, a positively- positioned and less hyper-vigilant localized information can always help build a stable personality with a less negative thinking and fewer negative emotions.

2. Extraversion

Extraversion is a relatively strong predictor of leadership emergence in groups. People with high extraversion are socially dominant, more assertive, and use their social skills to “take charge” of matters.

Localized content which has a balance of right information at a right place with an open forum for the customers to engage at the content development stage, or which provides references to the relevant information being hosted at various social sites, such as Twitter, Facebook, RSS feed and so on, encourages customers to be more socially acceptable and recognizable. In return, customers build up a long-term relationship with the product or the service that offers such localized content.

3. Openness

Openness promotes creativity. People with an open mind are more adaptable in changing contexts and can handle ambiguity effectively. This personality trait also propagates continuous learning.

A strategically well-visioned localized content always nurtures this dimension by encouraging the customers to better utilize the product or service through various ways of learning, such as a multimedia product tour or tutorial offered in the local language, or a product demo being hosted on sites like Youtube or Chirbit with voice-over in the local language. This type of holistic learning experience can bridge the gap of understanding between what customers want and what is being offered.

4. Agreeableness

Agreeableness has a positive relationship with social acceptance. A highly agreeable person is more compliant, conforming, and rule abiding, and, so, better liked by others.

Localized content which conforms to the rules and regulations of the region, yet does not deviate from the globally accepted standards, mitigates any non-compliance issue,  buys “peace of mind” for customers, and establishes them in line with the “think globally, act locally” policy.

5. Conscientiousness

Higher conscientiousness leads to greater effort and indomitable persistence, and makes people more disciplined and organized. It also helps people to be performance-oriented with the drive for superior results.

So, it is evident that localized content that is organized with high navigability, integrated search feature, and structured indexing can seed the concept of conscientiousness in customers’ mind and grow them as a matured users of the product. These days, the “think more, talk less” approach, being exercised by many localized content developers, is the true reflection of this personality dimension.

Although there is no established connection between these personality traits and localization, and neither does it guarantee impeccable quality of the content if certain are rules followed, but it definitely is a different perspective for examining human behavior and  tailoring the “help systems” to meet customer requirements.   I believe that future success lies in seamless research of these dimensions and their ever-growing influence in shaping the big world of localization.

References

• Robbins, S.P., Judge ,T.A & Sanghi, Seema.Personality and Values. Essentials of Organizational behavior.India, Pearson.pp. 21-23
• Wikipedia link to the Big Five personality traits

About the Author

Subhajit began as a foreign-language professional, and grew into a globalization expert and information developer. He’s worked with American Express and  Xchanging, and is currently with IBM. His experience includes localization, globalization, localization packaging,and information development in domains such as insurance, banking, finance, CRM, and IT.  He is pursuing a General Management programme from IIM, Lucknow.

Possibly related articles:

1. Nov-Dec 2009 Newsletter

- Urmi Roy

Organizations today are constantly challenged about how to design their information system so that it can be meaningful to the users. As they are seen to make huge investments towards infrastructure for information systems, it is important to consider the design or the organization of content in the information system.

A good information system comes from an understanding of:

• The business goals and business context of the organization
• The users using the system
• The content that will be a part of the information system

This article shows how you can design an effective information model using the above pointers. Most importantly, it aims to show the possible relationships between these components and how a comprehensive information model can be drawn up with an understanding of the organization’s business goals.

Before we start out to design an information model, we need to have a general understanding of business goals. What is a business goal or what is the reason for a business to exist? A business exists because it provides value to its customers through some kind of good or service.

Let us take an example of a product that a company develops and sells to its customers. In other words, by selling the right product, the organization delivers value to the customer.

But how are these goods or services provided to customers?

In case of large organizations, divided along departmental or functional lines, the different functional units collaborate together to provide these services. Each of these departments (e.g. sales, marketing, finance) has a specific role in the organization. However, when it comes to creating the value for the customer, they work together to make it happen. It is in this context that business processes are born.

Business processes look beyond an organization’s internal divisions and can be defined as “a set of related business activities that join together to deliver something of value (e.g. products, goods, services or information) to a customer.”

Taking forward the above example of selling the product, let us look at a typical high level business process “Sell to the Customer”. What are the steps involved?

• The sales team finds the customer.
• The marketing team assists the sales team.
• The development team develops the product.
• The distribution team dispatches the product.
• The finance team invoices the customer.

Figure 1 shows the business process graphically.

Figure 1 Business process

In other words we see that, in order to sell to customer, the work flows through the different divisions of the organization.

The process moves horizontally through the internal departments of an organization and at each stage some value is added before it meets the customer’s need.

Business processes are an alternative way to look at an organization as they change the emphasis from who does what to how it is done. Business processes are composed of several steps and can be further decomposed into several sub- activities and tasks.

With this generic understanding of business processes, we will take an example of business processes in the Telecom sector.

Business processes in the telecom sector are defined in the eTOM (enhanced Telecom Operations Map) guidebook, published by the TM (Telecommunications Management) Forum. These are the most widely used and accepted standards for business processes in the telecom industry and lay down the processes needed by the service providers. Here are some elementary concepts as we understand the eTOM framework.

eTOM is divided into three main areas, as shown in Figure 2.

Figure 2 eTOM processes

The eTOM framework shows both vertical and horizontal processes. Figure 1 shows the top-level (Level “0”) processes.

Vertical processes

The eTOM framework shows seven end-to-end vertical processes. The vertical processes reflect the main process areas needed to support the customers and to manage the business. At the heart of the eTOM, the focus is on the core customer operation processes of Fulfillment, Assurance and Billing (FAB) that directly support the customer.

Operations Support and Readiness (OSR) vertical process supports the core customer operations processes of FAB by setting up the operational environment.  Similarly the SIP area vertical processes support the core customer operations processes and the OSR process, and are differentiated from the core processes.

Horizontal processes

The horizontal processes on the other hand, reflect the functional processes and the expertise within an enterprise’s internal organization that are very much required for businesses to function. In other words, these processes support the execution of the vertical processes with their focus and expertise.

The eTOM model shows the business processes first from a high level view and then breaks it down to further sub processes. Figures 3 and 4 show the Level 2 and Level 3 processes.

Figure 3 Level 2 OPS processes

Processes are composed of several sub processes activities and tasks. The eTOM framework decomposes the level 1 processes to level 2 and level 3 process elements. Why is this required?

Process decomposition allows the framework to be adopted at different levels by service providers and the parties with whom they interact. Also, the actual activities under these, can be assigned to the above categories and leaves no room for ambiguity when adopted by service providers.

Figure 4 Level 3 OPS processes

With this knowledge of business processes, specifically in the telecom sector, let us see how information designers can apply this to the information design and structuring process.

In this context, the information designer represents a telecom equipment vendor’s organization. This vendor organization develops various network elements and databases that help the network operator to operate the network. The information designer is responsible for designing an information model that will aid the network operators.

To begin, we’ll take up one business process called Resource Management & Operations (RM&O).

This business process is responsible for managing all the resources (networks, IT systems, routers, servers etc.) that are used to deliver and support the services required by the customers.

From an information designer’s perspective this business process can also be known as Manage Network because it deals with the software and hardware and the tasks that are needed for building, operating, maintaining and managing a network.

So now we have established the business context in which this information system must work. The business context is to help the user manage the network.

The next thing that needs to be taken up is to identify the user.

Who is our user in this case? It is the network operator.

What does a network operator do?

A mobile network operator is a company that provides cellular phone services to customers. But how are these cellular phone services made available to the customers?

From the infrastructure point of view, in a typical GSM network, these phone services are made possible by a complex interaction between the different network elements, the databases, the messaging system, the hardware, and the underlying software that belong to the switching subsystem, the base station subsystem and the operation support subsystem.

However, even before the network can be rolled out to provide these services, the network operator needs to go through a long list of tasks. What are these tasks and how do we arrive at the tasks that a network operator needs to do to provide these services?

To re- emphasize, business processes can be further subdivided into sub processes, activities and tasks. Let us break up the main process into sub processes and come out with a process model that is reflective of the tasks that network operators need to do to provide telecom services to their end user.

Using the process decomposition method and by doing a thorough study of the operator processes, we arrive at the operator process model.

Listed below are some of the representative tasks that a network operator needs to do to operate a network and to manage the services.

• Plan a resource
• Install a resource
• Commission a resource
• Test and activate a resource
• Monitor a resource
• Troubleshoot a resource
• Prevent resource failures
• Collect billing data

For example, before rolling out a network, the network operator needs to plan the physical equipment and sites, the software that will be needed, the radio network, signaling, transmission etc.

Once the physical equipments have been identified, the process covers the tasks of installing, upgrading, managing, monitoring, preventing failures and all the other tasks required for operating a network and managing the services that are promised to the customers.

Now that we have an operator process model let us try to see if we can use the process model to design an information model that connects the information we provide to the processes and the tasks that operators do.

This brings us to the third component i.e. understanding of content.

Given that this information model needs to be designed to aid the network operators, we need to first identify the existing content in the telecom equipment vendor’s organization by the content analysis process.

This organization is divided along the different product lines and each of these product lines have enormous amount of content that act as supporting documentation to the products that the network operator uses.

The information model needs to reflect a system set consisting of a multitude of products – their underlying hardware and software that combine together to manage the network.

As information designers, as we start working on the information model we need to consider the following.

1. Create a content inventory that will identify all the proposed content for the system. What are the types of content that need to go in system set?  For example, this system set contains a complex mix of network elements and databases that are used by the Base Station Subsystem.
2. Identify patterns and content relationships. What are the network elements that are required for the user task of Planning, or what is the information that the user will need while troubleshooting?
3. Next, understand the type of information the user is looking for and analyze the existing material with the help of information types. What are these information types? Information types or units are the different types of information i.e. whether the information is procedural, descriptive, reference or task based. Once you have gone through the primary steps, see if the content (units of information) be put into the information model directly or is there some scope of dividing it further into subcategories?
4. Now you can start to organize content. Some guiding principles as you start organizing the content.

Chronological order

You can use chronological order whenever is it important to do the task in a certain order. It is good to use the chronological order at least in the user tasks of:

• Planning
• Installing
• Commissioning

Alphabetical order

The alphabetical order is another way of organizing content , whenever the order is not important. For e.g. the Reference category must always have an alphabetical order.

Frequency

Sometimes content can be organized based on the frequency of doing the task. Some tasks that need to be done more than others must appear before the less frequent tasks.

Products and Components

When many products combine together to be a part of a large information set, the product or the component structure can also be used to organize content under the subheadings. This works especially well for Installing, Upgrading or Descriptions sections in the information model.

Once you have gone through the above steps you have probably come up with an information model that closely resembles the following.

In addition to the operator processes you have to introduce additional categories of:

1. About this document set – this section acts as an introductory section and describes the document set. Some subcategories in this section are:
   • Guide to document set
   • Changes between release x and release y
   • Conventions and symbols used in this document
2. Descriptions – This is an additional category that does not belong to any single process. This section might contain high- level descriptions of products, features, functionality, architecture etc.
3. Reference – Yet another extra category that does not belong to any single process. Technical details of the system. For e.g. alarms listed in Troubleshooting sections might have detailed description here.
4. Legal and safety requirements – This section among other things might contain, disclaimer information that helps avoid litigation cases etc.

Does this information model make sense to your users?

Can you as an information designer see a pattern emerging? Are you able to map the operator processes to your information products?

Have you been able to look beyond product functionalities, beyond product lines and learnt to design the information from a business perspective?

If yes, you as an information designer have harmonized information across product lines by shifting the focus from what the product does to how the product helps the customer.

You have immensely helped the customer because the customer did not have to learn a multitude of product structures as they grappled with the various network elements at their disposal.

You have also helped the technical writer by elevating their role from being a mere product specialist to a process owner, which is very important in a global organization.

To re-emphasize, information designers play an important role in structuring the information. Once information designers start to think in terms of business processes, they start contributing to the business process and ultimately to the value chain that connects the organization to its customers requirements.

Acknowledgements

http://en.wikipedia.org/wiki/Business_process

What is Business Process Design and Why Should I Care? by Jay Cousins and Tony Stewart, RivCom Ltd

Enhanced Telecom Operations Map® (eTOM) The Business Process Framework  Addendum P : an eTOM Primer Release 4.5  GB921P Version 4.6.1 TeleManagement Forum, November 2004

About the Author:

Urmi Roy works as a lead technical writer at Citec Information India Pvt. Ltd. Her experience in technical writing spans across a wide range of technical writing activities, from pre-sales documentation to user documentation of different flavours. She has worked across different domains from Supply Chain to Telecom to BFSI. She has a Masters Degree in English Literature and a Certificate in Technical Writing from California State University, Fullerton.

Possibly related articles:

1. Review: The Practical Guide to Information Design

Admin Council for 2010 Announced

• President – Michelle Cherian
• Vice President – Rajdeep Gupta
• Secretary – Swaminathan Moorthy
• Treasurer – Saravanan Manoharan
• Immediate Past President – Sandhya Prasad

INDUS bags STC India’s Volunteer of the Year award

Savija T.V., Anagha Bhat-Chandratrey, and Anindita Basu (INDUS team) won the Volunteer of the Year award for “steadily marching forward with single-minded focus on their goal of regularly publishing bimonthly issues. The team introduced new and innovative publishing features and produced issues that were consistently content-rich, more colorful, and usable.”

Possibly related articles:

1. [Feb-2010] STC India Announcements
2. [June 2010] STC Announcements
3. [Apr 2010] STC India Announcements

2010 Candidates for Society Office Revealed

Jackie Damrau, Manager of the STC Nominating Committee, announced the 2010 slate of candidates for Society office. The election slate reflects the Society ByLaws which were amended to (i) Remove the Second Vice President position, (ii) Remove one Director position (iii) Change Director terms to two years, (iv) Allow Directors to serve two consecutive terms.

To view the list of candidates, visit STC’s Notebook.

Intercom’s 2010 Editorial Calendar Announced

The Intercom editorial calendar with issue themes and due dates for submissions, was announced by the Intercom editor, Liz Pohland. The author guidelines contain the details on content, style, formatting, submission, etc.

Possibly related articles:

1. [Feb-2010] STC Announcements
2. [June 2010] STC Announcements
3. [Aug 2010] STC Announcements

Time for my swan song. I have grown wiser from this experience and I hope we have all grown wiser with nuggets from the STC conference, learning sessions, regional and career conferences, this newsletter, and other interactions. We leave you with a few parting gifts that I’ll talk about in a bit.

I have conveyed our concerns about membership costs to the STC board and they agreed to give a waiver of the $25 chapter fee with immediate effect for India members while they consider the overall matter. A little parting gift. I think that’s a positive step that shows their openness to make changes here.

The conference was a tremendous success with 580 participants, a record 70 sessions in 3 tracks, a record sponsorship of over 28 lakhs in the difficult recession year with a tidy little profit of over 2 lakhs-another parting gift. The sessions included over 10 workshops, 50 paper presentations, 6 Sprint presentations, and the highly successful Project Management Progression with 7 speakers.

The conference was well-rounded and many innovative new sessions and features. There were excellent keynote speeches by Aravind Sitaraman, Cisco India Chief and Dr. Naresh Gupta, Adobe India Head. A VP-level panel discussion provided a strategic perspective. There was a special session for entrepreneur led by the Executive Director of The Indus Entrepreneurs  (TiE), Ravindranath. Education was covered in a debate on the importance and usefulness of a university degree in technical communication. A career forum presented lateral career paths for technical writers on script writing, localization, usability, program/product management, and gaming.

Everyone commended us on the superb organization of the conference. Thanks to Guru, the wonderful MCs, the brilliant and dedicated track captains, many STC volunteers, and the event management company who helped to make it such a smooth show. The evening party was a lot of fun with a talent show showcasing the alternate stars in our community. The stalls were well-attended and conducted many competitions. The usual quiz took a different format this year. The STC Annual General meeting was conducted and the new Admin Council was announced. Congratulations to everyone involved in making this conference into the all-time greats list.

We did a good job of rewards and recognition this year with Quarterly Awards, participation certificates for all who attended the conference, special joint certificates for the XnX pre-conference workshops, recognition to conference volunteers, sponsors, and speakers and a couple of new awards: Innovation award to Samartha Vashishtha from Adobe for creating the online conference registration form, and a very special India Chapter Distinguished Service Award to B S Gururaj for his long-standing and extensive contributions to developing this chapter.

The annual competitions were held, results were announced, and the winners felicitated. The STC Salary Survey was conducted and a report was prepared.

I thank all of you for giving me the opportunity to serve you this year. What I’ve learnt is that one needs a fair bit of time for this role. Time management was a challenge for me between my work, studies, home, and STC. A virtual Admin Council was another challenge—we opened a new online bank account and hopefully that should ease some of the logistics in the future. A third parting gift!

There is still a good deal of paperwork and files and not having any external staff to help with any of it bogs one down in administrative tasks. The small size of this chapter leads to other issues such as limited interactions in the mailing list, limited number of candidates for elected posts, limited points of view, and difficulty in juggling across regions. The new council has an uphill task and I wish them all the best.

What I’ll take with me are a lot of new friends and some best practices. My most enjoyable moments have been in writing this column. Keep in touch and may the force be with you. Over and out, Scottie. Peace. Etc.

Sandhya,
President – STC India Chapter

Possibly related articles:

1. [Feb-2010] Prez Talk
2. Report: STC India Career Day & Regional Conference
3. [Feb-2010] STC India Announcements

Vol XI, Issue 5

In this last issue for this calendar year, we have:

• Debarshi Gupta Biswas and Suranjana Dasgupta showing how usability combined with heuristics can help us produceuser-centric document.
• Vandana Rao giving an overview on content reuse.
• Melanie Doulton sharing strategies about surviving challenges.
• Rajdeep Gupta and Naveen D’Cruz sharing their individual experiences during STC’s Mentorship Programme.

You can also see the STC announcements and STC-India announcements, and plan for upcoming events.

And, as always, the President has a special message for you.

- Anindita Basu, editor
on behalf of the INDUS team, who hope to meet you at the STC-India’s annual conference in December 2009 at Bangalore.

Possibly related articles:

1. Aug-Sep 2009 Newsletter
2. Nov-Dec 2009 Newsletter
3. Jan-Feb 2010 Newsletter

- Naveen D’Cruz

One of my best pals called me up one day and asked me about the STC-India’s Mentoring Program, which I was totally unaware of. My friend gave a brief idea about the program module – Basic and Advanced and asked if I would be interested in mentoring someone on any topic related to technical communication. I was a little skeptical as I had not done any mentoring of this sort before; instead, I chose to be a mentee of a senior in the field.

I chose a simple topic for myself – Basics of Writing and Grammar. I had forgotten almost all the basics because in my current responsibility is only updating the documentation – not writing afresh or creating new content. Refurbishing my English grammar and writing skills was my core expectation. Commitment was the most important factor in this program; therefore I spared myself of other minor duties for the next three months.

My initial contact with my mentor was through mails and then we began using Skype. I sent my mentor some rewritten and formatted documents for a quick feedback. Because I work in the telecom domain, my mentor asked me to do a write-up on that domain.  I received comments on some area that were unknown to me, and helped me realize my mistakes and the rectifications required. See some of the comments I received:

In topic presentation:

• The document is monolithic. A hierarchical presentation would be better.
• From the top most level, cover each item in uniform depth and detail. If you do not want to cover them uniformly, after mentioning the various items in the introduction, mention that you are going to cover a specific item in detail or depth.

In writing style:

• Use a very simple language; particularly for technical content. Avoid technical expressions.
• Avoid parenthesis. You can use them if you want to introduce an acronym or an alternative term. Do not use to describe the behavior in an alternative condition or additional explanation.

I decided not to commit these mistakes in my next write-up; I fully intended to get some praise from my mentor. I wrote on cellular networks, and received further feedback on other mistakes that needed corrections – I was happy because these were not repeat mistakes and because I had got some new tips.

I had never content for screenshots and wanted to try it out. I finished a user guide on the Picasa tool provided by Google. Here, I learnt various parameters required to complete a user guide, formatting, using appropriate screen-shots, and content presentation. I then wrote another user guide – on Google Language Toolbar. This is an online tool and the representations differed from my previous exercise but my mentor took me through all the fundamentals.

The lessons learnt involved precious time and hard work. Time passed fast and the program came to an end. I spent more time on the program than I had expected earlier.  My mentor’s sheer motivation, confidence and follow-up yielded results – I reaped the sweet fruits of good writing from her.

The program is well-organized and must be repeated more often for writers like me – those who want to learn from the experiences of the veterans in the field.

About the Author

Naveen D’Cruz is a technical writer working in Bangalore.

Possibly related articles:

1. Mentorship Days

- Rajdeep Gupta

At the onset of the Mentorship program, I asked myself two questions:

• Do I have the capabilities to be a mentor?
• How will it help me in my professional career?

Thankfully, I have the answers to them after the completion of the program.

The Mentorship program organized by the STC India chapter 2009 has been quite an enriching experience. This is the first time that I volunteered for a mentor role. It contributed immensely to my professional growth as a mentor, and, most importantly, I am happy to be of some help to a fellow writer’s success.

I have been associated with STC India for some time now, and though I have been organizing and managing technical writing sessions, I wanted to work alongside a fellow writer and share the inputs that I have received in my career.

My mentee came across as a wonderful human being, who not only had a spark to learn, but was equally diligent. It makes a mentor’s job far easier, but then, the mentor too needs to be equally diligent towards the job. This program allowed me to work closely with a fellow writer and understand the areas that writers generally need guidance in. Such a program also gave me insights on how each writer’s working style is different, and what their approach os towards developing documentation.

The mentorship program went fine. It could have been better but, unfortunately, my mentee could not take out much time due to professional and personal assignments. Nevertheless, the mentee showed an appetite for learning. Over the mentorship period, I delivered sessions on the basics of technical writing, writing styles, and tools, suggested changes, and gave assignments.

The major areas of my mentee’s scope-for-development area in writing were in the inconsistency in the usage of terms, punctuation lapses, and grammatical mistakes. As my mentee was the lone writer at the workplace, entrusted with the entire documentation portfolio, it was a rather trying responsibility. In addition, because my mentee never had an opportunity to work with other technical writers, the person was at sea when it came to collaborative writing. Hence, I decided to give my mentee an overview of the product life cycle for a document, and then briefly touched upon other metrics of documentation. I talked about project estimation and was happy to see it being implemented in the online help created by the mentee.  We concluded by working together on a user manual for Google Talk.

As a mentor, I think the program gave me insights to the following:

• Giving impromptu talks on assigned topics.
• Gaining speaking experience that relates to specific career needs.
• Sharpen  listening and evaluation skills, and be patient.
• Gain valuable leadership management experience through leadership positions.
• Gain personal confidence that helps when speaking – whether to one person or one thousand.

The mentorship program has been a wonderful experience to me, and I am now confident about engaging in more such programs. I wish the program could be organized twice in a year so that it allows more time for mentors and mentees to collaborate and work towards their goals.

About the Author

Rajdeep Gupta is a writer for the last 5 years and is presently working with Misys. He is presently the Secretary of the India Chapter of STC and the Assistant Organizer of the Bangalore Technical Writers Meetup Group. He loves quizzing and is an avid blogger.

Possibly related articles:

1. Getting Mentored

- Melanie Doulton

“In the struggle for survival, the fittest win out at the expense of their rivals because they succeed in adapting themselves best to their environment.” –Charles Darwin.

This Darwinian tenet might be clichéd, but it is undoubtedly relevant. Nature gives us scores of examples of how adapting to changing environments marks the path of survival and its corollary, evolution.

Consider crows – birds that especially thrive and adapt around humans¹. For example, crows have been known to drop nuts from a height onto hard surfaces in order to crack them. Since this was not always effective with nuts with harder shells, such as walnuts, crows in Tokyo have been filmed² cracking nuts by using vehicle traffic! Even more mindboggling, these birds were then observed using pedestrian stop lights to retrieve the aforesaid cracked nuts from the road. There are several other stories of the ingenious nature of crows³ that demonstrate their ability to adapt and find ingenious solutions by breaking all conventions and coming out on top.

Given the fate of our ‘top dogs’ in the aftermath of the recent economic crises, might we benefit far more from becoming ‘top crows’ instead? I like to think that Darwin’s fittest are not the strongest, cleverest, or even the most skilled, necessarily, but are those withadaptive smarts, something crows seem to have in spades. Adaptive smarts are about finding innovative applications using existing means for outcomes that change the game. With reference to our hyperadaptive co-habitants, the crows, adaptive smarts meant no longer being content with just dropping nuts from a height to crack them, but discovering that unusual but easily available ‘tools’, that is, vehicles, can be used to crack them, therefore dramatically changing how they survive and, more importantly, thrive. Using adaptive smarts to alter your frame of reference and cross boundaries can enable you to discover variegated opportunities that are, moreover, less competitive. More options and less competition is the best kind of win-win situation.

So how is all this relevant to your technical writing career in these tough economic times? The rest of this discussion concentrates on strategies to help you strengthen your adaptive smarts. How you choose to implement these strategies is a highly personal process, given your own unique circumstance. The idea here is to provide some food for thought to help you develop your own particular brand of adaptive smarts.

Change your perspective

One strategy could be to expand your thinking⁴ to find new ways to adapt to dynamic, ever-changing environments.

For example, in the context of the current economic scene, jobs might be much scarcer now than they were a few years ago. But, looking at the problem from a different angle, the economic downturn has not affected all job markets equally. You could explore markets that might not be on your radar. Government agencies and non-government organizations such as the United Nations and Amnesty International are still hiring.

Another example might be teaching jobs. Teaching technical communication part time locally can be a great way to network and also provides a valuable resume addition. Or you might want to think about reporting for online technical magazines. Reporting on technological advances provides a different kind of writing experience and develops your skills in a new area.

Going solo by starting your own company might be another option especially if you have already considered it in the past. While it can be a higher risk option, it is also usually a more rewarding and exciting option.

Step out of your comfort zone

In addition to changing your perspective, another strategy is to go outside your comfort zone. Explore seemingly disparate opportunities that challenge you even when you have no experience or guarantee of achieving reasonable proficiency or success. Discomfort that comes from being out of your element is a great catalyst for change so find out what makes you uncomfortable and try it.

In the mid-nineties, when technical communication first became a viable professional option in India, the job market was highly competitive in the then exploding IT industry and career growth options were relatively limited. But, if you stepped out of the comfort zone and changed the frame of reference, an altogether interesting solution was apparent: During that time before the dot com bust, there was also a great demand for English-speaking technical writers in non-Anglophone countries. There was a camouflaged, but viable, job market in Western Europe and South East Asia, where qualified, English-speaking technical writers were in high demand. These overseas opportunities, while posing incredible challenges, also provided the added bonus of valuable international experience. If you’re willing to jump into unchartered territories, you might find a host of under-tapped opportunities and benefits.

Another really uncomfortable but valuable option: working for free. Doing volunteer work by offering free or heavily discounted technical writing services to schools, universities, religious organizations, libraries, etc., can expand your portfolio, keep your skills sharp, and build your network. Accepting that the market has shifted might mean turning the change into an opportunity for retooling and working at a discount or for free. One of the big advantages of this option is that it avoids serious gaps in your resume while also providing an opportunity to learn new skills and practice them.

Be open to inspiration

Sometimes cultural forces and conventional thinking can deter your natural creativity and tend to have the so called crab bucket syndrome⁵. It becomes nearly impossible to change your perspective or to step out of your comfort zone. To combat such potential-limiting obstacles, find ways to be open to inspiration. Try a new experience. Go on an adventure. It doesn’t even have to be related to work. Sometimes, it’s enough to sign up for a tap dancing class to jumpstart brainwaves. Delving into new adventures takes you out of yourself, changes your perspective and, most importantly, inspires ideas for change. And if you find you’re a tap dancing prodigy in the bargain, all the better! Or, for more focused inspiration, get involved with other professional communication groups. Such groups offer you networking opportunities that provide fodder for breakthrough ideas, at the very least. You can find inspiration anywhere; you just have to look for it.

All these strategies have worked either for me directly or for people I know. Developing your adaptive smarts by changing your perspective, stepping out of your comfort zone and being open to inspiration will aid you in navigating a rapidly changing world. With change being the only constant that you can count on, let’s learn from the crows how to crack a few nuts!

1. Known as synanthropic species.
2. Video clip from David Attenborough’s BBC documentary, The Life of Birds: http://www.babelgum.com/131346/attenboroughs-life-birds-crows-the-city.html
3. TED Talks Video: The Intelligence of Crows by Joshua Klein: http://www.ted.com/index.php/talks/joshua_klein_on_the_intelligence_of_crows.html
4. Breaking Out of the Box: Meaning and Means by Gerald Zaltman: http://www.acrwebsite.org/volumes/display.asp?id=7995
5. ‘It is said that if you want to keep a live crab in a bucket, put more than one crab in it. As one crab tries to climb out of the bucket, the other crab tries to pull it down.’ –The Happiness Factor: How to be Happy No Matter What by Kirk Wilkinson

About the Author

Melanie Doulton has been working as a technical writer in various capacities for over 14 years. A fledgling tap dancer, an ardent Impressionist art lover, she is currently a communications analyst for the Information and Communication Technology Division of the United Nations Department of Field Support in New York City. You can email Melanie at melanie.doulton@gmail.com.

This article originally appeared in the October 2009 issue of Southern Communicator, a joint publication of the Australian Societies for Technical Communication of New South Wales and Victoria, and the Technical Communicators Association of New Zealand. It appears here with changes.

The picture (crow on coins) used in this article is from http://thenonist.com/index.php/thenonist/permalink/crows_and_coins1/ and is used here with permission.

No related articles.

-Vandana Rao

The term reuse has several different connotations. In its most primitive form, reuse involves copying and pasting text. However, reuse is much more than just copying and pasting text. Reuse is essential in defining a unified content strategy; it can also help improve documentation processes and the quality of information products. Understanding different reuse methodologies and concepts and including reuse in documentation plans will enable you to define and set up an effective content reuse process.

Advantages of Reuse

The question of necessity of reuse, more so at the topic level, is easily answered today when resources are constantly under threat, budgets are under strain, and the onus is on developing more content with fewer writers: reuse enables you to manage more with less.

• Efficiency: It is easy to copy and paste topics, but when you do need to update all of them, it will be time consuming and tedious. When you write for reuse, you only need to update once.
• Consistency: Using the same content for manuals, guides, and online help ensures consistency across all the information products.
• Modularity: Writing for reuse encourages modular writing. Information structured in modules is usable, and easy to identify and find.

Methods of Reuse

Reuse is generally categorized into two main types – opportunistic and planned.

Opportunistic reuse is a common method of reuse. Opportunistic reuse is ad hoc, unplanned, and incidental. For example, in the midst of developing content for a user manual, you find sections of the online help that already contains information that you need. A quick copy-paste helps you create new content for your guide.

Planned reuse, on the other hand, is methodical, conforms to pre-defined reuse guidelines, and goes a long way in providing a return on investment (ROI). In planned reuse, you explicitly identify reusable content (such as existing feature descriptions in guides that can be reused in online help), define strategies to reuse it, and write new content that can be reused in the future.

Opportunities for Reuse in Documentation

There are several different ways in which content may be reused. Most of these may be fairly obvious. The following list is by no means exhaustive, and is only indicative of the innumerable ways to achieve content reuse.

• Template reuse
• Outline reuse
• Documentation reuse
• Graphic reuse
• Topic reuse

Even if you are writing for a documentation set where no planned reuse guidelines are in place, you will undoubtedly be familiar with the first four types of reuse just mentioned. Reusing documentation templates, outlines (such as reusing the table of contents of an existing installation guide to create an installation guide for a similar product), documents (in cases where products have similar components, each requiring documentation), graphics, images, and illustrations are all possibilities of reuse in documentation.

Topic, or even paragraph, reuse provides optimum advantages of reuse. Front matter, such as copyright notices, trademark information, document conventions are common examples of topics that can be reused across documents like installation, configuration, and user guides. Topic reuse can be extended to product overviews, architectural overviews, parameter definitions and so on, and applied across information products such as guides, online help, brochures, etc.

Reuse of templates and outlines help you in saving considerable time and effort. But these (templates and outlines) are a one-time effort within the documentation life cycle. In contrast, topic reuse is a continuous process, providing recurring ROI. Additionally, topics written for reuse are efficient, modular, usable, and consistent.

Topic reuse requires setting up a common reuse guideline that defines the principles for writing for reuse. If the planned reuse extends to a group of writers, topic reuse also requires the setting up of a collaboration plan.

Planning for Reuse

Reuse cannot just happen. Planning is essential to the success of reuse. When creating your documentation plan, ensure you include your content reuse plans.

• Identify reusable components of your documentation set.
• Understand that reuse has several connotations. Explore the various methods of reuse that are possible and identify the reuse methodology that works best for your documentation.
• Explore possibilities of using the authoring tools features that help to automate reuse.
• Define guidelines for writing for reuse.
• Educate your writers about writing for reuse. Set up collaboration between writers and provide training. If you are moving from a setup where reuse was not formally supported to a reuse environment, writers need to learn to write for reuse.
• Periodically review your reuse guidelines. Ensure that it is working as planned and that it continues to enable your documentation development process. Documents are live entities that need to change and adapt in order to be usable and useful to readers. Review your reuse processes to ensure that they are aiding the development process and not hindering them.

Reusable topics can be written and reused effectively if objective and tangible reuse guidelines are defined and applied systematically. Writing for reuse is not very much different from any other form of structured writing. It simply means that writers need to adhere to reuse guidelines in addition to style guides. Despite the fact that reuse appears to require additional effort on the part of the writer, the overall benefits of reuse outweigh the additional planning. Eventually, reuse not only helps in saving time and money, but helps writers write modular and usable topics.

References

Kostur, Pamela. 2008. How to Rewrite Content for Reuse: Part I. Retrieved October 15, 2009, fromhttp://www.dclab.com/reusable_content.asp

Ann Rockley, with Pamela Kostur and Steve Manning. 2002. Managing Enterprise Content: A Unified Content Strategy. New Rider Publishing. Chapter two, Fundamental Concepts of Reuse. Retrieved October 15, 2009, from http://www.managingenterprisecontent.com/

Will Tracz. 1990. Where Does Reuse Start? Retrieved October 15, 2009, fromhttp://delivery.acm.org/10.1145/390000/382702/p42-tracz.pdf?key1=382702&key2=5141105511&coll=portal&dl=ACM&CFID=15151515&CFTOKEN=6184618

About the Author

Vandana Rao (vandanasrao@yahoo.co.in) is a principal technical writer at BEA Systems (a wholly owned subsidiary of Oracle), prior to which she worked at Alcatel-Lucent and Terradune. With an interest in enhancing editing skills, she has recently enrolled in the Editing course at UC Berkeley Extension.

No related articles.

- Debarshi Gupta Biswas and Suranjana Dasgupta

The Digital Divide and Technical Communicators

In his famous book, The Inmates Are Running the Asylum: Why High-Tech Products Drive Us Crazy and How to Restore the Sanity, Alan Cooper, one of the greatest advocates of Interaction Design, introduced the term: “Cognitive Friction”. He defined Cognitive Friction as “the resistance encountered by a human intellect when it engages with a complex system of rules that change as the problem changes. Software interaction is very high in cognitive friction”.

This cognitive friction results in a digital divide between the software development community and software users. The digital divide, in turn, has a direct correlation with the usability of the application: how well can the software users learn and use the application or the product to perform their tasks and accomplish their goals. Today’s Technical Communicators can help bridge this divide and reduce cognitive friction by applying industry-acclaimed usability techniques to the documentation they produce toward accelerating user acceptance of the product. Less cognitive friction means better user adoption that results in fewer calls to tech support, higher customer satisfaction, and in the long run, better brand loyalty.

This Article describes how documentation usability combined with heuristics can play a pivotal role in producing user-centered technical documentation that fosters a satisfying user experience.

Usable Documentation Accommodates How Users Think

Studies by Knowledge Solutions, a leading provider of knowledge transfer and end-user adoption solutions, indicate that the astounding figure of IT projects failing, late, or over budget could be slashed by almost a third if more attention was paid to user adoption. Gartner, the world’s leading IT research and advisory organization, believes companies that spend more on application development but less on factors related to user adoption put projects at increased risk of failure. According to a study conducted in 2008 by the Sand Hill Group and Neochange, two leading consulting firms, the most critical factor for the success and return-on-investment of an IT project is effective user adoption.

Examples such as these have very interesting ramifications from a documentation perspective. Documentation can be effectively used to improve end-user adoption. Even the best software in the world with the most sophisticated features fails if people do not use it. And solid documentation can really help an unintuitive application overcome the challenge of poor usability. In a situation such as this, a Technical Communicator can suddenly become the most important player in ensuring the success of a product by assisting the users in performing their tasks with clear and crisp instruction-driven documentation.

Documentation that adheres to established usability principles, and that evolves beyond the conventional framework of detailed user’s guides nobody cares to read, can go a step further in matching the users’ mental model. This helps the users to find information quickly rather than following the wrong path and ending up frustrated. In his popular blog on the latest trends in technical communication, I’d Rather Be Writing, Tom Johnson writes:

“Invariably when I ask people how they prefer to learn new software, they respond, “I like someone to show me,” or “I like to play around in the system and then ask a colleague if I get stuck.” I’ve yet to hear the response, “I like long software manuals with lots of text in small print.” Usually people that prefer this also like to slam their fingers in car doors and chew on tin foil…While your users are searching through the help, keep in mind another key factor in the help scenario: your user is frustrated. He or she is a little impatient, possibly angry, and the tension is building with each unsuccessful click”.

In a nutshell, documentation should always address the correct emotional state of the users and should be predictable enough to point the users to the correct answer at their hour of need. Otherwise users would decide to wait on hold for technical support rather than leveraging the all-encompassing documentation to understand how a specific feature of an application works!

Heuristics for User-Centered Documentation

There is no cut-and-dried set of heuristic principles for evaluating the usability of documentation. Different opinionated discussion groups have come up with their own subjective list of usability criteria. the key and broadly representative findings. Following is a compilation that lists some of the key and broadly representative findings.

Documentation should match the real world

Cognitive scientists have studied mental models to understand how human beings make decisions in a variety of environments. Usability – the effectiveness, efficiency, and satisfaction with which users accomplish specified goals in a given environment – is connected to the mental model of the users to the extent that it predicts the action of an application as the users work on it. A classic example of how much the Human-Computer Interaction (HCI) experts have adapted the study of mental models to software usability is the simple Windows Calculator that has similar functionality and user experience to a hand-held calculator familiar to all of us.

Documentation, too, should be developed in such a way that it matches the mental model of the people that will use it to understand an application. Traditional documentation is based on the foundational assumption that users learn in a structured and linear fashion. Studies reveal that, while reading documentation, users do not follow a predictable sequence, do not read every word, and actually start acting on the information within a very short time. Increased usability in documentation design based on the mental model of the users has the potential to pay back handsomely in addressing the needs of these “impatient” users. To match the expectations of the real world, the documentation should have the following major attributes:

• It should be designed from a deep understanding of the tasks that users perform. This understanding can be gained through interviewing representative users to determine what tasks they perform, what information they need to perform these tasks, what terminology they use to describe these tasks, and what prior experience and prerequisite knowledge they utilize to perform the tasks.
• It should be well organized and properly chunked. This can also be achieved by interviewing representative users to understand which information is mission critical to them and which is less vital. Thus, applying information architecture techniques, essential topics should be placed at the top of the hierarchy, and the topics that contain less frequently used information should be placed at a deeper level.
• It should transform long procedures into shorter, interrelated procedures so that the users can stay motivated to perform the tasks rather than being lost in an overly complex and detailed set of information.
• In his classic article, The Magical Number Seven, Plus or Minus Two: Some Limits on Our Capacity for Processing Information, George Miller, the renowned psychologist, pointed out the limited capacity of our working memory in holding only about seven items or chunks of information at a time. This has intriguing implications for Technical Communicators. While developing documentation, they must take into account that users have limitations in processing information. To help users process information, documentation must let the users digest one chunk of information before forcing them to start dealing with the next one.
• It should be based on a skeletal prototype that undergoes usability review by the users. Based on the review, the structure and content of the documentation should be modified to accommodate the needs of the users. Usability testing can unearth the search keywords that the users will use to look for information, the navigation pattern the users follow, and the errors they make while working with the application, which the documentation can then anticipate.

Documentation should go hand-in-hand with the product

As soon as the users see part of the user interface, they immediately set their own expectations on what to look up in the documentation. Here are a few items that can ensure that documentation meets user expectations:

• If the users know that a piece of information is not available within the documentation, they will not waste their time looking for it. But, if they think that the information is available, yet they cannot find it after a period of unsuccessful searching, they are very likely to get frustrated. The documentation should have a well-designed index, one that contains key terms/concepts (and their synonyms), procedures, acronyms, abbreviations, and symbols used in the software. With the emergence of advanced techniques, like embedded indexing where a marker is embedded at each location in the document where a term is relevant, an index can act as a roadmap for technical documentation.
• The procedural instructions and explanation of concepts should reflect the language of the software, reducing cognitive friction. In this context, Geoff Hart, who has held key positions at the Society for Technical Communication (STC), observes, “I still recall with considerable frustration trying to figure out how to type French accents in an early version of WordPerfect-none of the half dozen standard synonyms for WordPerfect’s chosen keywords (“overstrike mode”, if I recall) were anywhere to be found”.

Documentation should be succinct

Usable documentation is always short and snappy. It provides information economically, but not at the expense of being incomprehensible, or omitting critical/useful information to reduce length. Documentation must be purposeful so that users get what need. In his article Heuristic Inspections for Documentation – 10 Recommended Documentation Heuristics, Vesa Purho sums it up wonderfully:“people working on a rooftop installing some hardware would not necessarily be delighted with nice multimedia CD-ROMs but prefer a laminated quick reference card”.

To develop succinct documentation, Technical Communicators must understand their audience well enough to identify what their needs are, and predict how the users expect to accomplish their goals. The documentation should also provide the following:

• Troubleshooting information to guide the users through common problems without ever explicitly stating that the workaround would not have been necessary if the software was properly designed
• Alternative functions or tools, and scenarios in which to use them
• Ensuring appropriate information is included, with references to additional help. In Geoff Hart’s words, “if I’m using Web-authoring software, I want a printed URL or hyperlink that takes me to the W3C tag references page and accessibility guidelines so I can look up this information quickly. Why waste your time including this information in your documentation when an authoritative group has already done all the hard work for you?”

Documentation should be task-oriented and user-focused

Usable documentation does not describe the product in meticulous detail, and is structured around the tasks that the users are expected to perform within the application. It should be organized by a logical grouping of tasks presented in a language familiar to the users. Documentation should be developed using a structured process that starts with the big picture and adds lower level of details. It should be free from excessively complicated references to other documentation modules.

Additionally, the documentation must not forget to address the unique needs of every set of users. It should support users with varying levels of knowledge on the domain and tasks. Technical Communicators must understand the users’ characteristics to successfully determine what documentation will work best for them. In her article, titled Developing Usable User Documentation, Rachel Campbell outlines the following checklist for developing a task matrix mapped to the user population:

• List the tasks vertically, and the audiences horizontally.
• Decide which topics are of interest to which users.
• Analyze the matrix:
  • Is the matrix full of Yes’s? Probably the topics are too broad to differentiate.
  • Are there empty rows? Possibly an audience has been left out.
  • Are there empty columns? Probably topics have been omitted.
  • If certain audiences only need a subset of the topics, an individualized document may be in order.

Documentation design should not be an afterthought

Standardizing the overall layout of documentation, especially in a multi-writer scenario, is critical to presenting information in a coherent form. Design acts as a means to an end: connecting the Technical Communicator that has information with the users that need it. Good design ensures that the users who will read the documentation can quickly get what they need to accomplish their tasks. Here are a few tips to ensure good and usable document design:

• Provide visually distinct macro information zones and micro information zones for scanning and reading, respectively. The high-level headings form the scanning zone while the reading zone is a visually denser area, providing more layers of information.
• Typography should pass the “Squint Test”. While developing documentation, the Technical Communicators should ask themselves these questions: Which chunk of information is more visible than others? Which chunk of information gets lost? Are the chunks and overall structure of the page distinct?
• Color should be used to command attention on critical information that the users must read, define specific foci, and identify what should take precedence.

Usability Testing for Documentation

In order to ensure that the documentation caters to the needs of its users, it must be safeguarded by a robust quality assurance system. Testing the usability of documentation is a practical solution to the documentation challenges faced by today’s organizations.

Common Documentation Usability Testing Techniques

A document with a pretty look-and-feel that does not help its users accomplish their intended goals is frustrating for its audience. Here are a few common techniques that can be used as a litmus test to identify if a document is usable:

• Observe representatives of the user population while they are reading the document, and question them to see whether they can perform tasks in a scenario-driven environment by following instructions outlined in the document.
• Conduct surveys and questionnaires for users or business partners to gather their feedback on the document.
• Apply a readability formula (such as the Flesch Reading Ease or the Flesch-Kincaid Grade Level) to determine if a document is suitable for its intended audience. Having said this, there are schools of thought that believe readability is driven by the perceptions of the individual readers, so a readability formula cannot be used to predict text difficulty.

Pilot Study on the ROI of Documentation Usability Testing

Elaine Ostrander conducted a study to identify the return on investment (ROI) with regard to documentation usability testing. The study was based on an over-the-shoulder usability testing of documentation, and formal laboratory study was not conducted. 11 participants from at least four different countries, with an average experience of over 10 years in usability testing, volunteered for the study. They were given a list of stages in usability testing, and asked to indicate the minimum, maximum, and average amount of time spent on each stage, and the corresponding hourly cost for each stage

The participants were also asked to report benefits of usability testing, although most of them could not quantify the benefits.

The study revealed that different stages of testing require varying degrees of labor and that the total cost of usability testing can vary widely. It also indicated that all the participants agreed on the following benefits of usability testing of documentation:

• Decreased need for customer support to augment documentation
• Costly errors created by poorly written instructions are eliminated

91% of the participants agreed on these benefits:

• End-user completes tasks faster using improved instructions
• End-user accesses information faster in final document

73% of the participants agreed on these benefits:

• Increased customer satisfaction and loyalty due to quality of final document
• Decreased need to rework before final publication
• Decreased need to publish after-the-fact fixes

Although there was low response on a quantitative measure of each benefit, the study generated a strong indication that the return on investment for performing usability testing of documentation was too large to be neglected.

Conclusion

Usability is the combination of effectiveness, efficiency, and satisfaction with which the users accomplish defined goals in a given environment. User-centered documentation matches the users’ mental model, thereby helping the users find information they want quickly and easily in their hour of need.

The list of documentation usability criteria is fairly subjective at this time, and various opinionated discussion groups have contributed to this. Usable documentation is based on a deep understanding of the users’ tasks, and this understanding can only be gained through interviewing representative users. Applying information architecture techniques, the content within documentation should be properly chunked so that the users can assimilate the information properly. Procedural guides should have a well-defined and searchable index that enables users to connect key application terms to their correct context.

User-friendly documentation is always succinct, but never at the expense of omitting critical/useful information. It should be developed using a structured process so that it starts with the big picture and gradually adds lower level of details, addressing the needs of every unique group of users. Finally, the documentation must be tested among a representative group of users, and their feedback should be incorporated to make sure that it has met all of the major usability criteria.

Bibliography

• Cooper, Alan. 2004. Preview of The Inmates Are Running the Asylum: Why High-Tech Products Drive Us Crazy and How to Restore the Sanity. Sams Publishing.http://books.google.com/books?id=04cFCVXC_AUC (accessed June 5, 2009).
• O’Hannigan, Patrick. 2002. Concentric Circles: Technical Writing as a Function of Usability. Society for Technical Communication.http://www.slostc.org/topics/usability/concentric_circles.html (accessed June 5, 2009).
• Guren, Leah. 2006. It May be GUI, But it Doesn’t Have to be Messy! In Other WORDS.http://www.ocstc.org/pdf/GUI.pdf (accessed June 5, 2009).
• Press Release. 2007. Poor User Adoption Increasing UK IT Project Failures. Training Press Releases. http://www.trainingpressreleases.com/newsstory.asp?NewsID=2908 (accessed June 5, 2009).
• Rothbart, Jason. 2008. Enterprise Software: Focus on User Adoption, Not Features. ReadWriteWeb.http://www.readwriteweb.com/archives/focus_on_user_adoption_not_software_features.php(accessed June 5, 2009).
• Johnson, Tom. 2007. Dealing with the Documentation Aspects of Bad Software – My Response to the Latest DMN Communications Podcast. I’d Rather Be Writing.http://www.idratherbewriting.com/2007/01/25/dealing-with-the-documentation-aspects-of-bad-user-interfaces-my-response-to-the-latest-dmn-communications-podcast/ (accessed June 6, 2009).
• Hart, Geoff. 2006. A Recipe for Designing Usable Documentation. Geoff-Hart.com. http://geoff-hart.com/resources/2006/usable-docs.htm (accessed June 6, 2009).
• Purho, Vesa. 2000. Heuristic Inspections for Documentation – 10 Recommended Documentation Heuristics. STC Usability SIG Newsletter: Vol 6, No. 4, April 2000.http://www.stcsig.org/usability/newsletter/0004-docsheuristics.html (accessed June 6, 2009).
• Davidson, Mary Jo; Dove, Laura; Weltz, Julie; 1999. Mental Models and Usability. Depaul University, Cognative Psychology 404.http://www.lauradove.info/reports/mental%20models.htm (accessed June 6, 2009)
• 2009. Minimalist Design for Documentation. Tec-Ed.http://www.teced.com/services_training_minimalist.html (accessed June 6, 2009).
• Dewey, Russell A. 2009. The Magical Number Seven Plus or Minus Two. Psych Web.http://www.psywww.com/intropsych/ch06_memory/magical_number_seven.html (accessed June 6, 2009).
• Hart, Geoff. 2008. Ten Technical Communication Myths. TECHWR-L. http://www.techwr-l.com/node/774 (accessed June 6, 2009).
• Gyure, Gloria M.D. and Kelley, Colleen S. 1996. The Joy of Indexing: How to Make a Good Document Better. Society for Technical Communication.http://www.stc.org/confproceed/1996/PDFs/PG379.PDF (accessed June 6, 2009).
• Campbell, Rachel M. 1998. Developing Usable User Documentation. Goddard Space Flight Center. http://aaaprod.gsfc.nasa.gov/TEAS/rachaeltea2/rc.html (accessed June 7, 2009).
• Quesenbery, Whitney. 2004. The Importance of Document Design. Society for Technical Communication. http://www.stc.org/intercom/PDFs/2004/200406_02.pdf (accessed June 7, 2009).
• Bowers, Nathan. 2009. UX Superpowers Revealed: “UX Vision”. UX Hero.http://uxhero.com/ux-techniques/squint-test/ (accessed June 7, 2009).
• Ostrander, Elaine. 2000. Usability Testing of Documentation has Many Benefits of Unknown Value. STC Usability SIG Newsletter: Vol 7, No. 2, October 2000.http://www.stcsig.org/usability/newsletter/0010-pilotstudy.html (accessed June 7, 2009).
• Escoe, Adrienne. 2001. Preview of The practical guide to people-friendly documentation. American Society for Quality. http://books.google.com/books?id=2jZ-VyEdIaAC (accessed June 7, 2009).

About the Authors

Debarshi Gupta Biswas has close to ten years’ experience in developing technical documentation on different lines of business and for varied sets of audience. Currently, he is a Senior Technical Communicator at Cognizant Technology Solutions.

Suranjana Dasgupta has more than twelve years’ experience as a technical writer. Currently, she leads the Technical Communication practice of the Kolkata (India) office of Cognizant Technology Solutions.

This article first appeared in the August 2009 issue of STC UUX Community Newsletter, Usability Interface, and has been reprinted here with permission.

Possibly related articles:

1. The Value of End-User Surveys in Testing Landing-Page Usability
2. Automation of Documentation Submittals via HP Quick Test Professional
3. RCO, Estimation, & Ratio Analysis Technical Documentation, Part 1

December 3-5, 2009 at Bangalore.

• About the conference: http://www.stc-india.org/conferences/STC-Bang-2009/about.html
• Agenda: http://www.stc-india.org/conferences/STC-Bang-2009/agenda.html
• Registrations: http://www.stc-india.org/conferences/STC-Bang-2009/registration.html

Possibly related articles:

1. STC India Conference 2009
2. Oct-Nov 2009 Newsletter
3. Report: STC India Career Day & Regional Conference

There was only one valid nomination for each Admin Council position, and the candidates, therefore, are elected unanimously. The formal announcement will be made at the Annual General Meeting during the STC-India conference at Bangalore in December 2009 (Date: Dec 4, Time: 6.30 p.m., Venue: Lalit Ashok, Bangalore).

The final list is:

• President – Michelle Cherian
• Vice President – Rajdeep Gupta
• Secretary – Swaminathan Moorthy
• Treasurer – Saravanan Manoharan

Possibly related articles:

1. [Dec-2010] STC India Announcements
2. [June 2010] STC India Announcements
3. [Aug 2010] STC India Announcements

STC’s 2010 Dues Structure and Membership Benefits announced

Membership fees, member benefits, and FAQs are at the STC blog.

Nominations for Simplified English International Standard Working Group

Because STC is a member of the National Information Standards Organization (NISO) and Localization Industry Standards Association (LISA), it can nominate experts to join the working group for the new Simplified English international standard. To nominate yourself or someone else, see the details.

STC Relaunches Online Buyers Guide & Consultant Directory

The updated guide, listing companies and technical communication consultants selling products and services, is here.

Atlanta Conference sessions now available

The sessions are available through SUMMIT@aClick and have full audio and video capture. Participants can see speaker materials, watch the audio/visual speaker presentation (as presented in Atlanta), and download an audio file. Conference attendees who paid the full registration amount have full access to SUMMIT@aClick and have received their unique passcodes and instructions to access the content. Others need to buy.

STC’s Live Learning Center has a FREE featured session (90 minutes) from the 2009 Summit, Introduction to Blogging: A New Technical Communicator Role, presented by Tom Johnson.

STC Goes Green with Publications

From 2010, STC will no longer publish printed versions of Intercom and Technical Communication; instead, members will receive email notifications with links to the online publications. Print-on-demand copies of each publication will be available at an additional subscription fee.

STC Continues Transition to Social Media Platforms

STC has transitioned its electronic newsletter, News & Notes, to a blog format. Postings can be expected biweekly. The blog, open to all, is here.

STC is also on Twitter (stc_org) and LinkedIn (Society for Technical Communication).

Possibly related articles:

1. 2010 STC Summit and Member Benefits
2. [Feb-2010] STC Announcements
3. [June 2010] STC Announcements

- Sandhya,
President – STC India Chapter

I wondered what to write in my penultimate article to all of you. I wondered if I have made any difference to our community. If I’ve managed to make a minor dent in a paradigm shift away from the importance of tools and years of experience to the importance of basic technical communication and leadership skills, I’d be thrilled.

A presentation I had made at an STC Regional Conference on the seven basic principles to be a world-class technical communicator encapsulates my message. If this message resonates with a few of you, I’ll feel satisfied. Do let me know your thoughts over email, or better still, in person, at the best ever STC Conference that will take place from December 3-5 this year in Bangalore.

With due regard to Stephen Covey, I propounded that we need to look at “visible skills” and then “invisible skills.”

Visible

Habit 1: Hone your core skill
Habit 2: Specialise
Habit 3: Professionalism (had to have an “ism”)

Invisible

Habit 4: Reliability
Habit 5: Act global
Habit 6: Make a difference

And finally …

Habit 7: Self-drive

Visible skills

Habit 1: Hone your core skill

Your core skill as a technical communicator is a mastery over the English language: written and spoken. Grammar should be immaculate followed by an understanding of context and style. You may ask why that is critical as you are well-versed in technology. You could use a spellchecker for grammar and perhaps use editors on your team to fix style issues. My answer: Your language skills are still the primary root of your career. You may be compared with native English writers and should hold your ground. How do you hone your language skills? Read. Speak. Practice.

Habit 2: Specialise in a domain

You can make a greater impact on your career growth if you gain domain knowledge in a particular area over the years or specialize in an area of technical communication.

Examples of domains:

• Technology: software applications, networking, telecommunications, middleware, databases, semiconductors, CRM, SAP
• Industry: banking and financial applications, aerospace, healthcare in a functional area

Examples of technical communication specialisation:

• Editing, Graphics, Usability, Production, Instructional Design, Localisation, Internationalisation, Knowledge Management

Habit 3: Professionalism (had to have an “ism”)

The first two skills will help you to be good at your work. But it’s not enough just to be good at your work. You need to be a good professional too, and that involves some soft skills (those dreaded words!).

• Understand your office culture and work within its values.
• Take notes. Memory can be fallible.
• Ask questions. You need to understand, and if you’ve understood, need to demonstrate that you have understood.
• Respect confidentiality. An easy way to lose trust is to repeat information given just to you or to forward sensitive mails marked to you.
• Demonstrate maturity, objectivity, good judgment.
• Do not indulge in office gossip. See my earlier PrezTalk article on Gossip.

Invisible skills

Habit 4: Reliability

Fill in the blanks: A rolling stone gathers no _ _ _ _
Think of people in your organization. Whom do you rely on? See Habit 2, Specialise. You can only do this if you:

• Work at least five years in a company
• Respond to emails promptly
• Meet your commitments, and if there are issues…
• Escalate quickly
• Manage perceptions
• Be consistent          … and so on and so forth

Habit 5: Act global

Interact well across people, teams, and cultures.

• Attack the problem and not the person
• Introspect when you get feedback
• Don’t discount yourself, others, your work, the situation
• This is a job! Maintain perspective.

Also see Habit 3, Professionalism. And Habit 4, Reliability

Habit 6: Make a difference

To your documents, your products, your team, your manager, your customer, your stakeholders.
How?

1. 1. Do an environment scan
   2. Understand pain points
   3. Understand how decisions are made
   4. Ask how you can help
   5. Align the wheels—individual, team, company
   6. Suggest process improvement
   7. Innovate on information

And finally …

Habit 7: Self-drive

Your manager or your company cannot motivate you. They can only create a conducive environment where you can achieve your potential. Then it’s up to you. So be:

• Self-motivated
• Self-managed
• Self-directed
• Self-learning

Take mentoring and coaching as required to become a well-rounded, independent professional.
I believe that there are many top-notch technical communicators and teams in India who deserve recognition, challenges, and to be treated on par with technical communicators anywhere in the world.

I can’t top that line, so I invite you again to the STC conference. If you haven’t registered for the conference yet, you can do so at http://www.stc-india.org/conferences/STC-Bang-2009/registration.html. A lot of detail has gone into this conference and we look forward to seeing you there.

No related articles.

Vol XI, Issue 4

There’s something new from this issue onwards – if you send us a subscription request, we’ll mail the newsletter to you.

In this issue, we have:

• B S Gururaj asking us which one has that slight edge – content or tools?
• Sharada Palagummi urging us to differentiate between information and knowledge.
• Sridhar Machani sharing tips on handling the document review process.
• Anne Sequeira sharing her experience about writing her first DITA topic.
• Uma Sastry concluding her two-part series on Articles.
• Hemanth Basrur showing how lateral thinking led him to find a different use for a software testing application.
• Virupaksha Math talking about his idea that lets users get a look and feel of a physical product without even setting their eyes on the product.
• Sandeep B tracing the evolution of some of the words we use in our daily work life.

You can also see the STC announcements and STC-India announcements, catch up with our learning sessions, and read our mails.

And, as always, the President has a special message for you.

- Anindita Basu, editor
on behalf of the INDUS team

Possibly related articles:

1. Oct-Nov 2009 Newsletter
2. Nov-Dec 2009 Newsletter
3. Simulating Hardware

- Sandeep B.

Have you ever—even for just one second—paused to actually trace the origins of the words—any word—you use in your writing or speaking life? Try it. It’s fun, instructive, and interesting.

If the previous paragraph has convinced you to trace the origins of words, congratulate me because I now successfully qualify for a membership in the (U.S) Democratic Party. I’ve now become a Democrat. The connection between the previous paragraph and my becoming a Democrat will be clear in a moment.  At the time of the American Revolution, the word Democrat had the pejorative meaning that we associate with the word Demagogue today—“a politician, leader or person who panders to emotions and/or prejudice”. In just over 100 years, the word Democrat had shifted so much in meaning that it is now the name of one of the only two American political parties. But look at what has happened to Democrat’s “parent” word, Demagogue. It now means the opposite of what it originally meant: a popular leader.

If the previous paragraph has confused you, re-read it.

Now what has happened in both cases is a gradual change in the original meaning of the word. Technically, the study of such changes in the meaning—or evolution —of words over time, across cultures and geographies is known as Semantics.

But there’s another, more fundamental aspect to changes in the meaning of words. It is the origin of words, the root cause, or the culprit. In our example, the word Demagogue originates from the Greek demagogos, which means leader (demos) of the people (agogos). And the study of word origins is technically known as Etymology.

As writers, it pays to develop a healthy curiosity about the etymology of the words we use everyday.  The “benefits” might not translate into a pay hike or promotion but it’ll help us become better writers eventually.  A brief list of words we use in routine technical writing parlance hopefully spurs thinking in this direction.

Today, we typically use the word manual in the context of a written document (User Manual). This word was imported into English from the French word manual which, in turn, has its roots in the Latinmanualis, meaning “fitted to the hand.”  The root of manualis itself is derived from the Greekmanus, which means “hand; strength; power over; armed force; handwriting.” These meanings have an echo even today in usages such as “manual labour” and “the user has to populate the fields manually (bah!).” In 1431, manual was used to mean “a service (Church ritual) book used by a priest.” Around 1533, this restricted definition transformed itself to mean “a concise handbook of any sort.” And viola! We have today the User manual, the Manual of Arms (military), a manual of mathematical tables, and so on.

While we’re talking about user manuals, let’s briefly dwell upon navigation. In very simple terms, to navigate is to find our way around something. Interestingly, the verb navigate came later than the noun navigation. This word has seen little change in meaning ever since it was first used in 1533, derived from the Latin navigationem, which means “to sail; sail over; go by sea; steer a ship.”  Navigationem is itself derived from Navis meaning “ship.” Although the original meaning is still in vogue, navigation is used today in the sense of “finding or helping find something—a place, an object, a direction, or information.”

From navigation to navigation aids (no, not the acronym). More specifically: Index and Glossary.

The lexicon seems to be quite fond of Index,notperhaps because the lexicon is itself an index of sorts but because Index yields a huge heap of meanings. For our purposes, it is simply a navigation aid, an alphabetical listing of words accompanied by page numbers. And it is 611 years old with roots in the Latin Indicis, meaning “forefinger; pointer; sign; list.” Does the word Index Finger sound familiar? However, it is also derived from Indicare, which, literally, means “point out.” The word Indicate has its roots here. Sometime in 1580, English incorporated Latin phrases such as Index Nominum andIndex expurgatorius to roughly give Index its current meaning. Index Nominum literally means an “Index of Names” while Index expurgatorius has a slightly tyrannical connotation. It literally means “specification of passages to be deleted from works otherwise permitted.” Post 1720, the usage of Index branched off in a hundred directions to variously mean “compile an index (of terms/words), refractive index, economic index,” and so on. For our purposes, we’ll simply to stick to generating Indexes for the documents we produce.

Sadly, the history of Glossary isn’t as colourful.  For the most part it retains its original meaning from the Greek derivative, glossarion, which means “obsolete or foreign word.” Around 1400, the Latinglōssarium made its appearance in English to mean, “a difficult word requiring explanation.”Glossary was originally used in the plural as glossaries, and alternatively defined as a “collection of textual glosses.”  Interestingly, the word glosses is itself derived from the (Middle High) German,glosen meaning “glow, or shine.”  This has resonance in the modern usage of the lip gloss, a beauty aid. But it remains that glossary, which today means “a list of terms in a special subject, field, or area of usage, with accompanying definitions” hasn’t deviated much from its original usage.

I should’ve started this piece with this word but I chose to keep the best for the last. While a lot of words are rooted in antiquity, some are deleted forever, some fall to disuse, some are revived from disuse, and others still, are rescued from extinction. Interface is a good example of the last phenomenon.

Interface is derived by combining the prefix, Inter, with Face. It is a fairly “modern” word in some sense because it was coined around 1880-1885. It originally meant “a surface forming a common boundary, as between bodies or regions.”  This word lay dormant for several decades until in the 1960s, the computer industry suddenly resuscitated it with the same sense of usage. Within the computer industry, interface generally means “a point of interaction between a computer and another system—like a printer or similar device.” However, its usage became pervasive quite rapidly and pretty soon, acquired newer usages. For instance, it is acceptable to use interface in the sense of denoting interaction between departments in a company or between areas of study: “we need to improve the interface between the documentation team and the HR team.”  However, using interfaceas a verb is generally frowned upon because you have better substitutes in interact, deal, work, or cooperate. Whatever the usage debate, it’s clear that the world of words owes immense thanks to the computing world for rescuing this word from complete oblivion.

You obviously don’t expect me to write an Etymology dictionary here—two such comprehensive (searchable) dictionaries already exist online if you are interested:http://www.etymonline.com/index.php and http://dictionary.reference.com/browse/etymology. If you are a steadfast devotee of the printed material like me, I highly recommend the Oxford Dictionary of English Etymology, the Chambers Dictionary of Etymology, or the “lite” Barnhart Concise Dictionary of Etymology.

In the end, Etymology is tremendously rewarding not merely because it’s akin to a journey in history, or an enjoyable hobby but because its real value lies in the range of possibilities it offers us in the world of usage. It instructs us without preaching. It helps us to both break the lazy habit of using words frivolously–like cycling or swimming, you can never “forget” it once you’ve learnt it–and to become more effective writers.

If you are unconvinced still, check out the origins of bless, document, web, content, and search.

About the Author

Sandeep B. has a weakness for words and masquerades as a technical writer. He can be contacted atdeepu.sandeep@gmail.com.

No related articles.

-Virupaksha K. M.

This idea won a prize at STC India Regional Conference at Bangalore in July 2009.

Software products are easy to demonstrate to clients – the products can be carried around or accessed electronically. But what about hardware products?  My product is a security panel for homes.  It is a physical product that is difficult to carry around and show to prospective clients.

My idea was turning this piece of hardware into a software simulation that would help users get a feel of the product, albeit electronically.  Users could play around with the simulator to learn about the product and its features; Marketing folks could carry it around and demonstrate the product features to prospective clients.

I took digital photographs of the various screens of the panel and created a PowerPoint presentation file where these pictures were arranged in the same sequence in which a user would see when actually using the panel. I then converted this presentation file into a PDF document. In the PDF document, I created transparent buttons on the page to exactly superimpose upon the user-input areas such as the numeric keypad, menu buttons, and so on. I then inserted links from source to destination screens. I limited the navigation in the PDF document to ensure that one could move to the next screen or menu item only by clicking the option keys or numeric keys (which actually were the transparent buttons with links to the destination pages). I then set the PDF document properties to open in full screen view. I also included user assistance (in the form of highlights) on each page, leading the user to perform the intended action.  For example, pressing a four-digit code on the numeric keypad would unlock the panel (a message would be displayed) and lead a user to the Welcome screen and then, appropriate keys would be highlighted so that a user knows which keys to click.  The key combinations would lead a user to the next screen, with scroll-menu buttons to navigate to succeeding and preceding pages, each with their own menu.

Users could thus get a real-life, hands-on experience of the product.

Tools used for the simulator: Canon S2IS digital camera, Microsoft Office Suite 2003, and Adobe Acrobat Professional 7.

About the Author

Virupaksha K.M., is an Electrical Engineer and an MBA from Bangalore University. He began his career as a Trainee Journalist with The Economic Times, Bangalore. He is currently working as Lead Information Developer with Honeywell. He presented a White Paper titled, “Adopting Mistake Proofing Methods in Documentation,” at the 2006 Annual STC Conference in Bangalore. He is a cinephile, an aspiring shutterbug, and an inveterate biker. He is currently preparing to run a full-marathon.

No related articles.

- Hemanth Basrur

This idea won the first prize at STC India Regional Conference at Bangalore in July 2009.

Are you a Web publisher or Web submitter who uploads documents manually? The primary role of a Web publisher is to publish content on the Web. The content being published could be in different file formats like html pages, pdf documents etc. A typical process involves a Web publisher uploading a document, entering the metadata for the document, and posting it to the Web. This effort is time-consuming. Is there any automated tool that can help Web publishers submit several documents automatically without having to enter the metadata of the documents manually and processing them? The answer is yes

At Hewlett-Packard (HP), where I work, Web publishers handle a lot documents that are in the pdf format. The content is processed using an internal Web publishing tool. The entire cycle, from uploading a document into the internal tool to posting it to the Web, takes about 15 – 20 minutes for each document. This effort gets multiplied depending upon the number of documents to be uploaded – the actual impact of this effort was driven home when HP decided to carry out a major migration project.

The migration project involves migrating approximately 2000 documents from the existing HP technical documentation Website to a new one over the next few months. Doing the project manually would involve tremendous amount of working hours.

While exploring alternatives for a more efficient process, we learnt about the HP Quick Test Professional (QTP) tool. HP QTP is an automated functional Graphical User Interface (GUI) testing tool created by the HP subsidiary Mercury Interactive.  The tool allows the automation of user actions on a web-based, client-based, or desktop computer application. Using HP QTP, a sequence of steps can be recorded as a macro, and the recorded script executed multiple times.

To migrate our documents, we used this tool.  We first recorded the steps involved in posting a document such as uploading a document into the internal Web publishing tool, entering the metadata, and posting the document. Then the variables, input formats, and so on were customized according to the environment. The inputs to the script (metadata of documents) were entered in an excel sheet. At runtime, the HP QTP script read the data from the excel sheet and posted the document automatically with minimal manual effort.

As a result of using the HP QTP script, we have been able to do batch processing of documents and have effectively reduced the work-hours by almost 50%, leaving us free to utilize the time thus saved for more productive work.

The major contributors to this idea are Amit S Pujar, Hemanth Basrur, Manjunath Raj, and Vino Gandhi M from the Information Engineering team; and Vivek Hebbal Sharanappa from the Build and Release Team in HP India Software Operations, Bangalore.

About the Author

Hemanth Basrur is a Senior Information Developer working at Hewlett-Packard India Software Operations (HP ISO) in Bangalore. He has over nine years of experience in technical communication. He can be reached at hemanth.basrur@gmail.com.

No related articles.

— Uma Sastry

In spite of having the thumb rules with us, we may still be at times unsure of placing the right articles. You may wonder sometimes like Sir Henry Higgins and say, ‘Why can’t we place the articles like the way it should be?’

While the names of rivers, mountain ranges, musical instruments, inventions, famous books, family, deserts, gulfs, peninsulas and forests are mentioned with a  ‘the’ , the names of planets, countries, continents, states, languages, mountains, lakes, streets, roads, parks, stations and public buildings are mentioned without a ‘the’.

We say: The Himalayas, The Ganga, The guitar, The computer, The bible, The Tatas, The sahara, The rain forests.

But we say: Earth, India, Australia, English , Mount Fuji, Dal lake, Cunningham Road, Hyde park, Bangalore city station, Vidhana Soudha.

(Of course there are exceptions such as the US, the UK, the UAE, the Philippines, and the Netherlands)

Let us look at these contexts to see how the usages go:

• A.R. Rahman plays the piano
• Marconi invented the radio.
• The computer is a revolutionary invention.
• Save the tiger. (not ‘save tigers’)
• Use the internet.
• Earth is a planet.
• The earth revolves round the sun.
• Sugar is bad for health.
• Please pass the sugar.

Now, try to figure out the difference between ‘earth’ and ‘the earth’, and ‘sugar’ and ‘the sugar’. Check whether it is ‘television’ or ‘the television’.

About the Author

Uma Sastry is an English language trainer. She be can reached at auma123@gmail.com.

No related articles.

- Anne Sequeira

When I first heard about DITA, I thought to myself, ok here is something new for me to learn and implement. I was wrong in a way. Though DITA was a new kind of documentation technique to me, what I didn’t realise is that I had in a way been implementing DITA in my procedures: I had all the elements of DITA in my procedures alright, but I had jumbled them all up. I had failed to realise that all I needed to do was not a drastic change in the way I write but — in the small and made-easy manner of DITA — change the way I presented what I wrote.

Discovering DITA was like discovering a feature you didn’t know your phone had all this while. It was sitting out there, waiting to be applied.

Now you may think that writing a DITA-compliant procedure is something you have to sit and rack your brains over. You may also feel that now you will take forever to write a procedure and it may run on for more pages than you wish. Well, I would say, that is not really accurate.

Using DITA actually makes your procedures concise and useful. You no longer have to worry about what fits and what doesn’t. Breaking your procedures into the various DITA elements helps you see whether certain information needs to be added, moved, or deleted. And then suddenly, when you begin to write procedures, you automatically start adding, deleting, and moving information around like you need to do with DITA. Before you know it, DITA has already changed the way your procedures look.

So how do you get started? There are many approaches and I feel this certainly depends on the writing style of each writer.

Maybe this will help:

• Identify your user goals
• Create task flows for any tasks you want to document
• Identify separate tasks
• Isolate concepts and reference information from your tasks
• Create a navigation map for all this information
• Fit in links wherever applicable
• Preview your information

When I wrote my first procedure in DITA, I first wrote the steps like you do in any procedure. And then, I worked on moving them around and classifying them into three kinds of DITA topics, which are:

• Concept
• Task
• Reference

But my work in DITA didn’t end there. I realised that blessed DITA has a further dis-integration of each topic. It was like taking your procedure and ripping it apart, exposing it for what it really is, making it open for scrutiny. And then, you notice, you need titles, descriptions and body sections under each topic, so your procedure would look something like this:

• Concepts
  • Title
  • Short_description
  • Concept_body
  • Related_links
• Tasks
  • Title
  • Short_description
  • Task_body
  • Related_links
• Reference
  • Title
  • Short_description
  • Reference_body
  • Related_links

And now you may ask, is this all? You may argue that you already implement all this anyway, without DITA. So I have to inform you that no, this is not all. The best and the most interesting part of DITA that sends a shiver down your procedure’s spine is here.

The Task and Reference bodies now have to be broken down to actually put some level of usability in your procedures. Here is how it should ideally look:

• Concepts
  • Title
  • Short_description
  • Concept_body
  • Related_links
• Tasks
  • Title
  • Short_description
  • Task_body
  • Context
  • Steps (ordered or unordered)
    • Commands (with UI_elements)
    • Sub-steps (with information, example, and results)
    • Choices
    • Information
    • Step example
    • Step result
  • Result (of the task)
  • Example (of the task)
  • Post-requisite
  • Related_links
• Reference
  • Title
  • Short_description
  • Reference_body
    • Examples
    • Section
    • Tables
  • Related_links

So you see that what you have actually done is identify and classify your steps into different buckets like example, result, information, commands, links, and UI elements. At this point it becomes easier to identify complete and incomplete steps or procedures. You need to ask yourself: Do I need to provide some information in this step, or does what I have provided, serve as one? Is some part of my step just plain information to the user or is it an example of some sort? Have I noted down results of user actions in steps where it is applicable?

You now have a right to question if you really need DITA and if it is worth the trouble.

If usability is what you are looking for in your documents, then, yes, DITA is the best way. If you need to make sure your procedures have no loop-holes, then DITA is your guide.

If you don’t want your users to scratch their head and have it ache while going through procedures that give them the information they need, but in a clutter-free form, DITA can change things for you.

I think I am ready to give DITA a real shot. Are you?

About the Author

Anne Sequeira is a Technical Writer with Sasken Network Engineering Ltd.  Prior to this, she was with Wipro and Satyam.  She has an overall experience of 4 years, with close to 2 years in technical writing. Anne can be reached at anne.sequeira@sasken.com and annesequeira@gmail.com.

Possibly related articles:

1. DITA Writing Tips

— Sridhar Machani

As a technical writer, it is not enough to document something and send it out for reviews. You must take the ownership of getting your work reviewed and incorporating the inputs from reviews. Getting your reviews done is a common challenge and, thereby, a pet excuse for the lack of accuracy and quality in documentation.

This article discusses tips to help you optimize the review cycle by managing your deliverables (organization, format, content), time (deadlines), and stakeholders (developers, managers).

Deliverables

1. Collate related docs.

A project often impacts several documentation deliverables or several chapters in the same deliverable. When you’re about to send excerpts, think about how best you can collate them so the reviewers don’t have to search for new or modified sections, or, worse, spend time thinking why the documentation is spread all over the place.

A useful approach is to name and attach the excerpts of impacted sections in a logical order (page, chapter, deliverable), and explain each attachment (metadata – sequence, the functionality it covers, page numbers and so on).

2. Send MS-Word format along with PDF.

Most publishing systems have capabilities to generate documentation output in PDF, HTML, and Word formats. Reviewers would find it easier to include their comments in a Word file, rather than copy-paste each item of content into e-mails and share their comments against each item.
It would also make sense to include references (links) to the complete deliverables, so that the reviewers can refer to them to better understand the context of the new or updated documentation.

3. Mark the sections.

You can mark the exact sections that were added or modified so that the reviewers can visually find the sections quicker. Typically, change bars are used in the case of PDF outputs. If your editor prefers to mark the editorial notations on printed paper, why don’t you print the sections yourself and strike out the irrelevant content before handing them to the editor?

Timeline

A best practice would be to share your documentation plan with the stakeholders. It should contain each deliverable and the estimated date of completion of each stage. Get it approved and address any concerns before you begin your work.

4. Provide enough time for review.

Enough said.

5. Fix deadlines.

In your communication, mention and highlight the last date for sending review comments. Your documentation plan should match these deadlines.

6. Send reminders.

We all need them and so do the reviewers.

Stakeholders

The teams of project and product management, subject matter experts, test validation, services and technical support are usually the stakeholders. Identify the key stakeholders who need to be included in all communications, especially in the progress and status of the documentation.

7. Include all the stakeholders; do not broadcast.

For each communication, it can be tricky to decide the list of senders from a group of stakeholders. One thumb rule is to decide whether they need to know the information you’re trying to convey. For example, you probably don’t need to include the managers when you’re sending a document for technical review.

8. Live review – initiate a working meeting with stakeholders.

When a topic of documentation is likely to generate conflicts (accuracy, scope, relevance, location in a deliverable), or is likely to cause a delay in its review, setup a teleconference with all the key stakeholders and get them to review the topic ‘live’. This is sometimes called a working meeting, and works best to resolve outstanding issues and concerns. Be prepared to moderate the discussion and get all of them to agree on a common decision. Disclaimer: use this sparingly and with caution.

9. Keep managers in the loop; escalate if needed.

There would be some topics or deliverables that get deadlocked, when nothing works and things seem to be beyond your control. That is the time to engage your managers who could use their experience and authority to get things done.

10. Build confidence.

Be prompt in addressing the review comments. The next time you send your documents, the reviewers know that the time they spend on reviews is not wasted. More often than not, they would be open to more queries from you.

About the Author

Sridhar Machani is a Technical Writer at Wipro Technologies. In his spare time, he doubles up as a Web design and branding consultant. He spends most of his energy at http://sridharmachani.com.

No related articles.

- Sharada Palagummi

World, particularly the ITC world, is abuzz with the word knowledge sharing.  Most of us thoroughly agree that knowledge must be shared.  Often, the sharing is viewed only in the context of the product development teams.

However, what about the users?  We, the technical communicators, information developers, or whatever we prefer to call ourselves, are supposed to help our users in using our products efficiently.  So, I guess we are the ones responsible to share our knowledge with the users.

Fortunately, sharing our knowledge with users is easy.

Let us study two samples of user instructions for the Edit menu of Windows Explorer.  Let’s compare them for their content and be agnostic to language, presentation and formatting.  The user I have in mind is someone who needs to learn how Windows Explorer works; not someone who is using it for some time.

So, there you are.  It doesn’t take a Herculean effort to share our knowledge; does it?

About the Author

Sharada Palagummi has a Masters in Statistics, worked as a lecturer for 7 years and then, about 12 years ago, became a technical writer. She knows French, Italian, Japanese, and Chinese. She can be contacted at sharadap@integramicro.com.

Possibly related articles:

1. Knowledge Transfer

- Gururaj B.S.

If you overhear a team of experienced technical communicators discussing or arguing with emotional rhetoric, you might realize that they are debating over the importance of Content vis-à-vis Tools.  It’s an interesting debate based on the fact that a majority of technical communicators today are focusing (sometimes more than necessary) on the tools in their jobs.  While tools are important, they don’t drive the direction of content, which is the king.  So you now understand who follows whom.

In the context of this article, I’ll emphasize how tools have started following the path of content in transforming the face of technical content being delivered to customers.  Let’s begin with a fundamental assumption that we all understand and appreciate the concept of single-sourcing, reuse, repurposing, and dynamic creation and publishing of content.  They may sound like a bunch of catchphrases, but they are ways in which content creators and publishers can maximize their Return on Investment (RoI) by improving their internal authoring and publishing processes.  I use Adobe products, so I’ve picked some features in Adobe authoring tools, which have been introduced or enhanced recently based on the emerging trends in technical communication.  The purpose of this article is not to compare authoring tools or their features, and I am sure other authoring tools or products not referred to in this article (read competitors) support equally good or even better features.

A few years ago, no one probably expected that technical communicators would consider or discuss XML because the scope of technical communication was limited to creating or producing a set of documents (what I call the run-of-the mill products), including user manuals, administration guides, online Help, release notes and so on.  It’s important to note that some or most companies were producing reams of printed documentation and shipping them to customers.  Legal binding or commitment is one of the reasons why companies still produce and ship printed books even if it’s not profitable for them.  However, people’s reading preferences are changing, and not many customers insist on printed documentation anymore.  In addition to the production costs, technical communicators creating content for printed books have to follow many complex production procedures, among many other things, such as the following:

• Optimizing the PDF for print delivery
• Setting crop marks and regions
• Applying a different authoring template (sometimes)
• Dividing content into multiple volumes, based on the length of content
• Working with the print vendor or production department to produce high-quality PDF or PostScript (consolidated and separate files for each volume or chapter)
• Creating covers and specifying binding types like shrinkwrap, cornerstitch, and so on

More importantly, writers working on print documents have to complete their documentation in all respects at least a month before the product release date, especially if the printed books and the online documents are released at the same time.  This situation becomes more complex and unmanageable if your content is translated into other languages and the localized documents are printed and sold to customers.  The same bunch of production procedures (some writers call them nightmares!) should be followed by the localization teams (read vendors).  If your company does not have a dedicated program manager to manage localization vendors, you might end up educating the localization vendors about production procedures and working with them closely to produce printed documentation.  What this means is that you as a writer will spend more time addressing production issues, and I do not endorse that approach.

When companies continued to invest in printed documentation, they probably needed a system to increase their writers’ productivity and decrease the cost of producing content separately for printed manuals and online documents.  In some companies, printed documentation cannot be done way with, and I am sure they will be more than happy to get rid of their printed documents.  Here is an anecdotal story about how printed books are used (or not used) by customers.  When a company conducted a customer survey to find out how their documentation is used by their customers, one of the customers invited the company to visit their office.  When a team of representatives went to this customer’s office, they realized that their printed books were used as door stoppers!  That’s quite useful, right?

Nonetheless, the need for reducing costs and increasing productivity resulted in single-sourcing, which simply means that a single source of content is published in multiple output formats.  For example, the source content in Adobe FrameMaker is published in HTML, CHM, or other help output formats.  This concept of single-sourcing has some obvious advantages, such as the following:

• Consistency in content
• No need for purchasing a separate license for an online Help tool
• Opportunity to reuse a lot of existing content (user manual and online help, for example)

I see this trend as a key driver for Adobe to introduce a multitude of single-sourcing features in their technical communication products.  Before FrameMaker 8 was released, Adobe had almost dropped their “RoboHelp for FrameMaker” solution as they continued to support MIF import in RoboHelp.  Initially, MIF import in RoboHelp was not great because the mapping or association of styles used in FrameMaker documents wasn’t meant for styles to be used in HTML help topics.  In Adobe FrameMaker 8, in addition to improving the MIF import feature, Adobe introduced several new features, such as the following:

• FrameMaker 8: Conditional text processing based on conditions with Boolean operators
• FrameMaker 8: Filtering of content based on attribute values
• RoboHelp 7: Importing ToC, Index, and Glossary from FrameMaker source content, setting pagination properties, defining a standard pattern for names of HTML topics converted from FrameMaker content, mapping FrameMaker styles to their RoboHelp peers, defining context-sensitive markers in FrameMaker and converting them into context-sensitive IDs in RoboHelp

In addition, to cater to the single-sourcing production requirements of technical communicators, Adobe introduced two new features in RoboHelp 7.  The standalone version of RoboHelp, whose license is sold separately, supports the addition of FrameMaker source files to a RoboHelp help project.  You are essentially copying the FrameMaker content into a help project.  In the other RoboHelp 7 offering, which was sold as a component of Adobe’s first-ever Technical Communication Suite, you can link to FrameMaker documents.  In a way, it’s similar to import by copying or by reference.  When you link a FrameMaker file, the file is referenced from its original location. If the FrameMaker file is moved from its original location, the FrameMaker file in the RoboHelp project displays a broken link.  This is a great feature, in my opinion.  Again, I want to highlight that it’s one of those features driven by emerging content trends.

Content practices and trends are dynamic, and it is good, in a way.  Users of technical content are embracing new trends like interactivity, context richness, ease of use and access, and relevance.  Paragraphs in an online help topic are making way for interactive simulations, video tutorials, or feature walkthroughs.  For example, Adobe Captivate enables you to develop simple movies and simulations, and you can save them as an SWF file.  You can insert such Captivate movies in FrameMaker documents (versions 8 or later) or RoboHelp projects (versions 7 or later).  This feature is particularly useful if you want to break the monotony of text-based content.

Now let’s consider DITA, one of the most widely used (misused?) terms in technical communication today.  I am not going to talk much about DITA because we keep hearing and learning about various aspects of DITA.  If FrameMaker claims to provide end-to-end support for DITA today, in FrameMaker 9, it is because of DITA’s popularity as a topic-based authoring methodology.  Why did Adobe bundle the DITA application pack with its FrameMaker product?  We all know the answer.  Topic-based authoring, such as DITA, is the order of the day, and it makes sense for the queen to sing a I-support-the-latest-trends song while following the king

Nowadays, we see global, geographically disbursed teams in technical writing departments.  Multiple authors sometimes work on different topics in the same book.  This trend led to the evolution of multi-authoring support and version control in authoring tools.  Although these tools don’t offer a full-fledged configuration management system, something like ClearCase, they are bundled with a simple Windows-like interface for basic source control tasks.  RoboSource Control, which is shipped with Adobe products, is a classic example.

Like a spring, beginnings of all things are small.  What start as simple content trends continue to transform into much bigger things like content management, workflows, dynamic publishing, automation, and so on.  This transformation is another reason why FrameMaker 9 offers support for out-of-the-box integration with a Content Management System (CMS).  I hope Adobe will soon offer a “mini CMS” with its FrameMaker or RoboHelp!  I am kidding, of course

In conclusion, I’d like to reiterate that the queen (tools) follows the king (content).  While the queen is important, the king is critical.  Therefore, I take this opportunity to urge all of you to focus more on Content while creating your documents.  The basic purpose of any tool is to simplify things, and a tool always has a limited set of features.  You can learn them on the job through experience.  Content, on the other hand, is critical, and it drives everything else. Period.

About the Author

Gururaj B.S. is a senior documentation manager at BEA Systems (an Oracle company).  He is the owner of Technical Writers of India (TWIN) portal, registered community, and mailing list.  He is a former president of the STC India chapter.  He is a weekend guest faculty teaching technical communication to undergraduate and graduate students at Christ University, Bangalore.  He has written content for IGNOU’s text book on Scientific, Technical, and Medical Editing for a PG Diploma course.

You can send him an email message at gururaj.bs@gmail.com.

Possibly related articles:

1. Five RoboHelp tips

Learning Sessions at Chennai

• July 25, 2009
  • • • • Stepping into the World of Technical Writing – Vidula Sundaram
• September 19 , 2009 at Element K, Chennai
  • • • • Documentation Metrics – Tharoor Gopalakrishnan
        • Being Successful Technical Writer – Manish Mohan
        • Knowledge Management – Mahesh Rajagopal

Learning Sessions at NCR of Delhi

• September 19, 2009 at Oracle
  • Introducing FrameMaker 9 – Benny Joseph
  • Technical Writing in the Times of Recession – Nandini Gupta

Possibly related articles:

1. [April-2010] Learning Sessions
2. [June 2010] Learning Sessions
3. [Aug 2010] Learning Sessions

STC-India pilot library launched at Pune on Independence Day

The library opened at Pune on a pilot basis for 3 months and is currently open for residents of Pune. STC members can become members of the library for free. Non-STC members can become library members for a one-time enrollment fee. If the library is well-used, STC-India hopes to open libraries at other locations and expand the existing catalog of books. If anyone is interested in hosting, volunteering, or sponsoring this library at other locations, contact Kumar Dhanagopal (kumar.dhanagopal@stc-india.org). Information about this library is available at http://www.stc-india.org/library.
The task-force that made the library possible: Kumar Dhanagopal, Edwin Skau, Frederick Menezes, Samir Gaonkar, Subash Babu, and Makarand Pandit.
The book donors that made the library possible: Scriptorium Publishing, Abigail Samuels, Uday Chava, Oracle (who helped to ship the books from abroad and locally).

STC-India’s blog for technical writing job advertisements

STC-India’s new initiative is at http://techwritingjobs-stcindia.blogspot.com/. Recruiting companies can directly post a job ad by sending an email to the following e-mail address:stcindiajobs123.technicalwriting@blogger.com.

Mentoring programme of 2009

STC-India conducted a three-month mentoring programme during May 2009 to July 2009 with a purpose of knowledge sharing. Sharada Palagummi was the manager of this programme. All those who completed the programme found it beneficial, with some of them rating the programme 10 on 10, and volunteering to participate again in the next round. A few could not complete the programme, mostly because of the work pressure in the current financial situation of the industry. Sharada would like to thank all the participants.

STC’s Technical Communication Body of Knowledge Task Force

Makarand Pandit, of STC-India, was appointed to the task force, with the responsibility to maintain “Strategic Oversight of International Audience & Issues”.

Quarterly Rewards and Recognition Awards for 2009

Anindita Basu won the *Volunteer of the Quarter* award for the second quarter of 2009. Sandhya Prasad, chapter President, announced thus: “I appreciate her diligence to sticking to STC commitments and deadlines despite having a full professional life. That demonstrates excellence above the ordinary, and in recognition of that quality, the STC India Rewards and Recognition Comittee and the Admin Council unanimously selected Anindita for this quarter’s award.”

Contest: STC-India’s 11th Annual Conference, December 2009, Bangalore

The STC-India conference committee ran a contest to seek ideas and suggestions about the conference agenda, topics, and overall plan from potential participants. The winner of the contest is Percy (Alfred), who gets a free registration for the STC-India conference to be held on December 4 and 5 at The Captiol, Bangalore.

Possibly related articles:

1. Oct-Nov 2009 Newsletter
2. [Aug 2010] STC Announcements
3. [Aug 2010] STC India Announcements

2010 STC Summit; Dallas, Texas: Call for Proposals

STC’s Technical Communication Summit 2010 will be held between May 2 and 5, 2010 at the Hyatt Regency Dallas at Reunion, in Dallas, Texas. The Call for Proposals is now open athttp://www.softconference.com/subs/stc/2010/. Proposals can be submitted and updated online until 10:00 AM ET, Monday, 5 October.

STC Offers Online Certificate Courses

Beginning in September, STC will offer four online courses where participants can earn a certificate. The courses are divided into 90-minute sessions and presented live online, 10:30 AM–Noon ET, over five to eight weeks. Individual sessions may also be purchased without a certificate. The courses are:

• Undiscovered Country: Master Writer
  Five sessions beginning 29 September–27 October, Sharon Burton
• DITA from Legacy to the Future
  Eight sessions beginning 29 September–21 October, Bernard Aschwanden
• TechComm 101
  Seven sessions beginning 12 October–23 November, Leah Guren
• Technical Communication Manager
  Six sessions beginning 27 October–1 December, Saul Carliner

More about the courses are here: http://www.stc.org/edu/online-certificate-courses.asp. The courses are priced as follows:
$595 member, $995 nonmember; Student: $295 member, $995 nonmember
Individual Sessions (without certificate):$149 member, $259 nonmember; Student: $79 member, $259 nonmember.
Discounts are available for group attendance from the same company. For these special prices, contact Lloyd Tucker (lloyd.tucker@stc.org).

The STC Single Sourcing SIG site at http://stc1ssig.ning.com is now public

All pages except the Members page can be viewed by visitors to the site but only members can post content. To request membership, use the “Sign Up” link at the top right of the Main Page.

Member benefits: STC’s Notebook

STC’s Notebook is a blog that replaces the monthly electronic newsletter. News stories, pertinent announcements, and informative articles will be posted frequently as the blog grows and changes to meet the Society’s needs. Visit STC’s Notebook at http://notebook.stc.org and sign up for the RSS feed.

Member benefits: STC’s Job Seeker Boot Camp

STC’s Job Seeker Boot Camp is a free program and is for members who are currently seeking employment or wish to expand their contract work. The Boot Camp includes unlimited access to the STC Career Center, unlimited access to more than a dozen articles written by and for technical communicators with tips and advice on finding a tech comm job, access to audio podcasts by well-known STC recruiters, and the latest STC Salary Survey. To sign up for the Boot Camp, visit the Job Seeker Boot Camp webpage http://www.stc.org/membership/job-seeker-boot-camp-intro.asp.

Member benefits: STC’s Salary Database

STC’s Salary Database provides more than 100 pages of detailed regional and industry specific statistics on the number of jobs and salaries for technical writers. The report covers 160 municipalities and 21 non-metropolitan areas in all 50 states, the District of Columbia, and Puerto Rico. View STC’s Salary Database at http://www.stc.org/2009/08/STC-Presents-Government-Data-on-the-Job-Market-for-Technical-writers.asp.

STC on Twitter

http://twitter.com/stc_org

Possibly related articles:

1. [Feb-2010] STC Announcements
2. [Aug 2010] STC Announcements
3. [June 2010] STC Announcements

- Sandhya,
President – STC India Chapter

Have you ever tried to create a team brand? Most of us have, or have at least heard of, team vision, mission, goals, and other elements that comprise a team charter. How about a team brand? Think that only a company can have one? Your team can have one too.

How much of it can be used overtly depends on company, branding, and environment guidelines, but it’s a great teambuilding and morale boosting exercise to create your own team brand. It works well in creating some cohesion in work teams that work across functions or organisations.

I’ve done this exercise multiple times with various teams with wholehearted success each time.

What are the elements of a team brand? Here are some ideas:

• Team motto or tag line
• Team colours
• Team logo
• Team font (why not? We’re in the info design business, aren’t we?)
• Team song
• Team mascot (it could be a soft toy, a plant, even a pet!)
• Any other ideas? Write and let me know if you can add to this list.

After creating your team brand, can you display it anywhere? Consider the following questions:

• What are your company branding guidelines? Are internal logos permitted?
• What is the environment in the company? Are you a unique team or part of a larger team? In the latter case, it’s probably best to balance your team identity with that of the larger entity?
• What’s the size of your company? A small company may still be trying to establish its own brand and may not want additional sub-brands. Large companies usually have very stringent rules about the use of logos and such. A mid-size company may be more open to individual team branding and may even actively promote it. Find out.
• What’s the purpose of your work team (if members are working in different organisations). Will a team brand help the work at hand?

Once you have your branding elements ready, you would need to decide how you would like to display your brand.

• Team web or wiki page on the intranet – the most common place where you can safely use your team branding. If appropriate, the branding can be used on an external web site.
• Team presentation or movie — We need team presentations on many occasions:  when giving status reports, when introducing the team to others, to promote the team. A team movie is a fun take-off on this idea and will stir the creative juices of any doc team.
• Team newsletter – a great place to include brand elements would be in a newsletter that informs people about the activities of your team.
• Team brochure – Consider having a softcopy/hardcopy brochure about your team that is a handy reference guide to your team.
• Team poster – a fun way to showcase your team and make each member feel valuable.
• Booth design — If your team participates in any conferences, such as employment fairs, the brand elements and products can be used in designing the booth.

STC already has a well-established brand and we have tweaked STC India branding from the main brand. An example of an external work team branding.

The activities of the STC India chapter are mentioned elsewhere in the newsletter. The various cities are active and the annual conference work is going on full steam. The agenda is almost ready and will be published by the end of the month. Plenty of time for you to get an idea of what’s on offer. A lot of you have given wonderful ideas and we’re implementing many of them for the conference. This time, I wanted to introduce parallel tracks so that we have more to offer to a greater cross-section of people.

I’m driving the LnM (Leadership and Management) track and plan to introduce a couple of new sessions: Progression and Career Forum. The progression gives you an opportunity to sample a number of leadership topics in a different format. The Career Forum will have invited speakers talking about lateral opportunities for technical writers. More about these sessions closer to the conference.

I hope most of you are planning to attend the conference. If you’re in Bangalore and in town during Dec 3-5, you should definitely attend. Folks from other cities, a great time to visit cool, green Bangalore, so get ready to pack your bags.

Bangalore chalo!

No related articles.