Corporate Value Program (CVP)

CVP offers a variety of options, tailored to meet organizations’ technical communication needs. You can choose between memberships for all your staff or just a few.

The benefits include: E-memberships for company employees; transferable membership, if employees leave the company; special CVP rates on select STC goods and services (not available to employees directly); special CVP rates on training and education offerings; eligibility to introduce your organization’s products/services/events to STC members; recognition on STC’s web site.

Here is the link to our CVP page on the STC web site:  http://www.stc.org/membership/corporate-value-program

One of the biggest benefits is the transferable membership – this allows the organization to reap the continued benefit of STC membership – the benefit is not lost when an employee leaves. The CVP benefits both large and small teams.  The CVP is a tailored program that emphasizes STC membership, shaping the field and profession, and allowing access to the technical communication marketplace.

The cost for your group to join as a CVP is:

• 10 members: flat base fee of $1,900
• 11-25 members x $185 each
• 26-50 members x $180 each
• 51-75 members x $175 each

Special Interest Group (SIG) memberships may be purchased for $10 per person. Membership in a local chapter may be purchased for $25 per person.

The more people in a group, the more money saved as part of this program.

Possibly related articles:

1. STC India News & Notes, May-June 2011
2. STC India News & Notes, March-April 2011
3. STC Announcements

Vol XIII, Issue 6

Hello everyone! As the year draws to a close and we bring you the last edition of this year’s newsletter, we thank everyone who has been a part of the Indus experience in 2011. Thanks to all the contributors who have shared their knowledge and expertise and readers for their feedback and comments.

In this edition we bring you the round up of the STC India Chapter’s stellar event, the 13th Annual Conference which was a success yet again. Rachel writes about  managing a government portal, Sandhya Ravishankar shares her experience as Operations Manager in a large documentation services firm and her thoughts on technical writing, and Manjula Kandula decodes science writing. We also bring you the award winning PowerEdge R810 Hardware Owner’s Manual, which won at the STC Annual Conference. This issue also has an interesting read on user assistance for mobile devices by Monalisa Sen and Amrita Chakravarty. Read the regular updates on STC news and announcements here.

A the Indus team signs off for 2011, we look forward to a great team, contributors and readers in the next year. Do stay tuned for updates on the next year’s editions.  Wishing everyone a very happy and fruitful 2012!

- Anupama Gummaraju and Sreeraj Nair

Possibly related articles:

1. July – August 2011 Newsletter
2. September – October 2011 Newsletter
3. Nov-Dec 2010 Newsletter

Introduction

Times have changed! Most grandparents hardly struggle with cell phones today. Parents are active members of social networking sites and at times, share friends with us. Domestic help asks for a phone reminder to get bread, next morning. Well, life without mobile phones is history!

Long gone are days when a mobile phone was used only as a phone. Every mobile phone today offers more than just that, whether it is sending or receiving e-mails, reading, being in constant touch with friends through social networking sites or simply maintaining a to-do list. Everything in today’s world is in real-time, whether it is getting to know the cricket score or that your friend has lost his wallet! The world is literally in our hands and the picture below aptly describes this transition.

In the past, the built-in features of the mobile phone were the selling factors for consumers. However, smartphone operating systems now offer the ability to run third-party applications enabling users to load their handsets with varied applications, tailored to their personal needs.

A recent study showed that thirty-six percent of U.S. mobile consumers now have smartphones. The advent of smartphones has brought about a whole new segment of mobile device development and usage. Manufacturers focus on the structure and look of the device and the applications available, to enhance the usability of the device and help in greater user adoption. iPhone’s launch of the 3.5 inch display area started a revolution. However, many years later, the trend changed to a larger display area and “Apple has been credited for being the major force behind many recent design changes”.  Ross Rubin, Executive Director of industry analysis for NPD Group mentioned, “Apple’s iPhone addressed many of the form factor issues that had prevented users from easily performing tasks, such as using their phones to surf the Web…”

Mobile World: Possibilities of Assistance

User assistance has an important role to play in smartphones. Preparing documentation in the form of online help, embedded help (tooltips and interface text), and dedicated help pages for the mobile phone are just a few of the new age opportunities for technical writers.

In addition to creating documentation, writers can also contribute their expertise in other areas of mobile app development. They can use their technical writing experience to suggest intuitive names for the interface elements, such as button names or menu names. They can also test the applications being developed for the smartphones from an end user’s perspective.

Speculations

Although the mobile industry has opened up new avenues for writers, there are a number of challenges still to be overcome.

People use mobile phones for multiple purposes: accessing e-mails, finding directions, sending text and multimedia messages, recording videos, capturing images, downloading various applications, making online transactions, playing games, social networking, reading books, watching movies, listening to music, and of course talking. All this can be done using one small device anywhere — a crowded bus, a subway train, a low-lit room — to name only a few. So what are the challenges faced by a writer?

In addition to the above points, each device has its own operating system, user interface, icons, navigation methods, and standards. Moreover, smartphones are getting smarter and more advanced each day, so the writer must keep abreast of all the new advancements.

The challenge therefore lies in grabbing the attention of the users and in providing them optimal information that would make their life easier. So, the task of the writer is to plan far ahead, stay in tune with the ever-changing mobile application world, and design and develop content for users keeping in mind all these points.

Readiness to Create

With the advent of the smartphone era, new avenues have opened up for technical communicators. It is a field with numerous challenges in uncharted waters. Most writers are accustomed to writing for medium to large applications that require extensive documentation. But in the case of a smart mobile, the screen space is limited and the GUI is much more intuitive. So, the first question a writer must ask is “How much documentation does a smartphone need?”

The key to writing mobile documentation is to convey adequate information in as short and simple a style as possible. To do that effectively, the writer must be able to:

Understand the Smartphone Interface

Some smartphones are touch-based; others use the QWERTY keypad, whilst many boast of both (inbuilt and standard keypad). Each mobile application on a smartphone serves a unique function with different navigation and complexity. The first and foremost task of the writer is to understand the smartphone interface and the working of the various mobile applications on the smartphone.

Understand the Target Audience

The smartphone audience is active and web-savvy. They often use the mobile phone as an “on the go” pocket-sized computer. They require the most relevant information within a few seconds. The skills of a writer involve gathering fundamental or key information for such an audience and avoiding verbosity.

Design a Template

While creating the style sheet, a writer needs to keep in mind the limited display space of the mobile interface. The writer must appropriately define the stylistic elements, for example, font type, font size, font color, and spacing; to achieve little or no scrolling.

Develop a Table of Contents

The Table of Contents (TOC) is an essential garment of any documentation. In a smartphone, it is sometimes difficult to navigate back and forth across screens. The TOC should therefore be succinct and easy to maneuver.

Devise New Terminology

A technical writer must develop appropriate terminology that would suit the mobile user’s temperament. The terminology used to describe a task on a mobile must be spot on, depending on the type of smartphone: touch-based, QWERTY, or both.

Some of the major conflicts in terms of verbiage that a writer needs to resolve are:

Write it Right

The writer must exercise expertise in writing, editing, and rewriting the content to make it short and comprehendible. Procedures have to be short and to the point and the content must be skillfully divided into meaningful sections. A major chunk of effort involves maintaining links to related sections or to additional information. However, too many links can make navigation difficult.

Create Minimalist Documentation

While writing content for a smartphone, the aim of a writer is to adopt a minimalist approach with optimal usage of words and phrases. Minimalist documentation does not imply providing less information; it denotes isolating relevant and important information and presenting it concisely through an appropriate template and language.

Examples:
To achieve minimalism, the writer can:

Design Graphics that Fit

Using images can be a bit tricky so it is best to keep them to a minimum. However, while designing graphics, the writer must ensure that they fit the available screen space and are compatible with different screen display types: 1-bit, 2-bit, and full color. Large detailed images are best avoided as they might lose resolution and obstruct the main content. Black and white images with simple shapes and clean lines are appropriate and go well with all color schemes.

Develop an efficient “Search” system

Searching for information on a touch-based smartphone is not an easy job. One method of making information accessible is to create context-sensitive topics along with an exhaustive index. The writer must work with the developers to design a quick and effective search system.

Some Android phones offer means to maximize the search functionality by enabling users to download applications that “enable deeper searching”. Users can configure the tool to search for specific information. “Any application that you’ve installed that has searchable items (such as Twitter, eBay, and Amazon Kindle) can also be enabled from this screen.”

To search for information within the phone, users need to tap the Search option and select the relevant location on the search tool.

Google Gesture Search is another such tool which enables users to search for information with almost a single tap on the screen. Using the Settings window, users can configure which section needs to be searched.

Tools and Technologies

A number of tools can be used for creating documentation for mobile devices: Adobe RoboHelp 8.0 or above versions, Madcap Flare 6.0 or above versions, Author It, and FastHelp. (This whitepaper focuses on the use of Adobe RoboHelp 8.0 and Madcap Flare 6.0)

The help files and manuals can also be transferred through cloud storage. In other words, the files can be uploaded to the cloud and then accessed from mobile devices.

Adobe RoboHelp 8.0

RoboHelp 8.0 can be used to generate a help document for mobile devices by creating an electronic publication (ePub) output for single source content using Scripting Power. ePub files can be read on any mobile device such as, Android, iPhone, Windows Mobile, and Blackberry with an ePub reader. ePub can adjust the size of the text according to the size of the screen on which it is displayed.

The prerequisites for generating an ePub output using RoboHelp 8.0 are the ePub Generator Script and a 7zip executable (both of which can be downloaded). The script can be customized and imported to RoboHelp using the Script Explorer and an ePub output can then be generated and ported to the concerned mobile device. This output can be viewed using an eBook reader.

Madcap Flare 6.0

Madcap Flare 6.0 or above versions can generate a help output for the mobile through the WebHelp Mobile output target, see Output. The help output can be viewed from any mobile device with a micro browser.

To generate the help output for mobile using Madcap Flare 6.0, the writer will need to carry out the customary activities of creating a stylesheet, help topics, TOC, index, and skin. Madcap Flare has in-built mobile skins which makes skin definition easy. After organizing the content, the writer can validate the preview before generating the mobile output.

Traditional Help versus Mobile Help: A Comparison

This white paper discusses the characteristic style of writing a help topic for a typical web-based or desktop application versus a mobile application.

Figure 1 is a screenshot of a Microsoft help topic on adding content controls to a template:

Figure 2 is a preview of the mobile output of a help topic created using Madcap Flare 7.2. It describes the process of adding a contact on a touch-based smartphone.

Comparison between Traditional Help and Mobile Help:

The following table provides a comparison between the traditional help and the mobile help:

<Traditional Help Mobile Help
The overview is detailed. The overview is succinct.
Instructions are elaborate and content-intensive. Instructions are brief and to-the-point.
Topics are generally distinct from one another. Similar topics are clubbed to avoid repetition and redundancy.
The terminology is traditional and suited for the device on which the help will be viewed, for example, a PC or a laptop. A distinct terminology is coined to suit the audience and the device on which the help will be viewed, for example, Tap is used instead of Click.
The style and template are designed for a typical application viewed on a PC or a laptop. The styles and template are designed keeping in mind the small screen space of a smartphone.
Graphics are used wherever required. Graphics are kept to a minimum to avoid unnecessary scrolling.>

Conclusion

At one go, both traditional help and mobile help are similar and distinct from each other. Both extend the capabilities of a writer from a form, style, and content perspective. However, in case of a mobile help, the writer needs to move away from the tools, techniques, and mindset of an application-based help and “think inside the mobile device”.
Smartphones are quickly becoming a necessary possession thus making it equally essential for a technical writer to create effective documentation for such devices. Recent trends necessitate writers to come up with improved ways of creating documentation and assisting users to work with different evolving technologies effectively.
So, the next time your neighbor clicks the help link in a smartphone and finds the information useful, let’s hope you were the one who created it!

References

About the Authors

Monalisa Sen – With 5 years experience as a technical writer, she is currently part of the Cognizant Interactive department in Cognizant Technology Solutions. She has led a team of writers in multiple projects. She has experience working in different business domains such as Banking, Insurance, Hospitality, etc. She has completed her Masters in English from Jadavpur University, Kolkata. Her interests include reading, watching movies,  photography, and travelling.

Amrita Chakravarty — She is working as a Senior Content Specialist at the Cognizant Interactive department in Cognizant Technology Solutions. She has 4 and a half years of experience as a technical writer and has worked as a project lead in multiple projects. She is a Masters in English Literature from Jadavpur University at Kolkata. She loves reading books, watching classics and world movies, listening to music, and writing.

No related articles.

• The STC membership renewal period for 2012 is underway. Dues are same as in 2011. Dues for SIG have gone down! Referral discounts remain as is. And MadCap software is again paying for your STC membership. Read more details about 2012 membership here. All STC members must have paid their dues by 29 February 2012 to be eligible to vote in the election.
• STC’s Chapters and SIGs hold regular events throughout the year, many of which are virtual and open to all STC members. Bookmark the Community Events page on STC’s Notebook and keep an eye on events from STC’s communities!
• The certificate course schedule for 2012 is starting to take shape, with a few courses scheduled.
• STC president Hillary Hart shares a wonderful midterm report of all the STC activities, initiatives, and plans here.
• The 2012 slate of candidates for STC office is announced here.
• STC recently unveiled a new member-centric ad campaign, with testimonials from members talking about the value of the Society. Do you have a similar story? Would you like to be part of this new campaign? Visit here for more details.

Possibly related articles:

1. STC Announcements
2. [Dec 2010] STC Announcements
3. STC Announcements

Rachel

Recently I was asked this question in an interview: ‘Who should manage a government portal; IT people, marketing people or the content team?’

Turf wars have been fought over this ever since the Web first appeared, but the question never goes away. Ownership and management of any large web site is still hotly debated as departments fight for the right to own and manage the site, or wriggle away in disinterest.

The answer remains the same: managing a portal requires as much commitment and skill as developing the portal in the first place. IT, content and marketing people need to cooperate closely from the very start. Look for the team with enthusiasts, eager to understand all that’s new and changing, people who already know a lot, but also know what they don’t know.

Technical communicators are rare creatures—you straddle the IT-communications gulf, and so you are ideally equipped to work in this role.

If the organization already has a content team, that label implies an ideal mix of skills and sufficient understanding. But many organizations don’t have a content team. Business units produce and publish their own content, and other content work is shuffled off to the communications team as needed.

Disasters happen when a portal is managed solely by an IT group who leave all content issues to the communications team. Or an IT group without anyone who can write clearly and simply. Or an IT group that doesn’t realize that without clear content, the portal is worthless.

Disasters also happen when the wrong kind of communications team manages the portal. You know what I mean! Some comms teams are right up to date with web writing requirements. They understand the influence of words on search results, they know how to create content that’s accessible, usable, readable and findable. If they don’t know how technology affects the message, they’re eager to learn. Unfortunately, other comms teams live in a ghetto, without influence or energy. Secretly they wish that all things technological, including the Web, would vanish in a puff of smoke.

The marketing team could work OK as portal managers, but that would be pretty unusual. The gift that marketers can bring to portal management is active, up-to-date expertise in the culture of social media.

So, the management team for a government or other portal needs to include people with IT and communications skills (that’s you!) as well as modern online marketing savvy. It’s the skills that matter, not the current location of the right people.

About the Author

Rachel McAlpine (BA Hons, Dip Ed) is known internationally for her work in promoting quality web content. Since 1996, Rachel has been an independent consultant in all aspects of online content.

Rachel McAlpine’s 31 books include six about writing. Write Me A Web Page, Elsie! and Crash Course in Corporate Communications are widely used in New Zealand, Australia and the Pacific Region. Crash Course is sponsored by the Institute of Chartered Accountants of New Zealand and used in their Professional Competence Programme. It is also used as a textbook by the New Zealand Institute of Management for their popular course on Workshop Communication.

Despairing over the mountain of unusable online content, Rachel joined forces with Alice Hearnshaw to create CONTENTED, a smart system of online training for web and intranet authors. CONTENTED: content that makes people happy (the blog), carries on the QWC tradition.

Rachel is a forthright and entertaining conference speaker. She tackles many aspects of web content, from accessibility to search engine strategies.

Possibly related articles:

1. Eye-opening: Dr Naresh Gupta on the future of content

The air around the Hilton at Chennai bore a sense of expectation from December 1st to 3rd this year. There were excellent reasons. For the next 3 days, Hilton was to witness a congregation of technical writers, editors, managers, instructional designers, web designers, usability engineers, and more, to participate in the 13th STC Annual Conference. With 250 delegates from various companies like  Infosys, Qualcomm,Adp, Cadence, Progress software, Nokia Siemens Network, Dell, Oracle, Fidelity, Avaya, NetApp, and various others coming under the same roof, it was destined to be special, and it turned out to be so.  The conference was sponsored by Adobe, Author-it Corp, Citec, Contentmarket, Oracle, Vestas and Madcap.

Pre-Conference workshop on December 1st:

Six workshops of 3 hours each took place on December 1st. A mixture of both project management and tools workshops enabled the participants to pick and choose. Close to 80 people attended the pre-conference workshops.

Conference opening on December 2nd:

The following morning, December 2nd, saw quite an unexpected turnout of technical communicators. The organizers were stunned to see the last minute registrations. After the STC India President delivered the address keynote speech, P Kiranmayee enlightened the gathering with her talk on the vision of technical communication.
It would be unfair for me to talk about all the conference presentations because I have managed to attend only a few. But the general feedback from participants was that the conference presentations helped them identify the business aspects of technical writing and laid a path for technical writers to analyse those issues in real-life scenarios.
After that it was the time to put on the dancing shoes at the networking and cocktail dinner.

Final Day Conference Activities

The final day of the conference had presentations on Minimalism, Managing Localization, Workflows in Architecture, Conditional Text in DITA, Making the transition into content management and lots more. I was able to attend couple of sessions on the final day and each of one the topics had so many take aways.

Everyone was geared up to witness the all-important panel discussion comprising stalwarts like Francisco A, Sandhya Ravishankar, Uday C, Giridhar B, Latha S,  which was moderated by Gyanesh T and Nandini Gupta. Each of the panellists threw light on the following areas: How to create exam objectives and decide their weight? What are some common guidelines for drafting the questions?, Does one require instructional designing experience to create exams?, How to decide about the format and level of difficulty of questions? And how to go about writing and reviewing the questions while maintaining their confidentiality as much as possible?

Conclusion

Amidst all this knowledge sharing, the conference was a hub for companies to set up their stalls, not only to promote their companies, but also to solicit feedback from the delegates. In addition, there were organized contests and a number of awards to give away. The 13th STC Annual Conference at Chennai proved to be a showcase for sharing knowledge and dispersing the diversity of technical communication.

I take this opportunity to acknowledge the efforts of a multitude of STC India volunteers and chapter officers in continuing to support our activities and initiatives.
Here’s wishing all a prosperous 2012!

Possibly related articles:

1. Prez Talk
2. Prez Talk
3. Prez Talk

Sandhya Ravishankar

In this edition of Experts Ignite, we talk to Sandhya Ravishankar, who joined Citec Information in 2005 and currently works as Operations Manager. Sandhya has a special interest in modular documentation and has worked in DITA based modular documentation environments in varied domains like Telecom, Manufacturing, and Power & Automation.

Tell us about your experiences as an operations manager.

It has been an interesting journey these past 4 years, in my role as the primary point of contact for both internal and external customers of my organization. Citec Information India has grown from a predominantly Telecom & IT industry focused documentation company to an information management company, providing a wide variety of information services for diverse sectors like Energy, Manufacturing, Health care & Automation. Witnessing our growth in a steady and controlled manner in multiple industry segments with an enhanced service portfolio has been a fulfilling experience.

This role requires a bit of both, leading and following, in order to interpret Citec’s strategy for our Indian operations and translate them into everyday practice.

What difficulties did you face in Citec with such a large group in terms of work/ project? What is your day to day routine in terms of work?

Our challenge was to build teams for new domains with varied competencies and to maintain high quality, sustained service for a number of multinational customers in very diverse domains. So we have worked on our processes, competence development and systems. We are privileged to be part of a global organization which is at the cutting edge of Information management solutions.  Selecting the right people and helping them develop their competence by training and working in complex documentation projects for global organizations has helped in overcoming in these challenges.

Day to day routine varies with the organizational needs at any given point. When we are building new teams, it means participating in team selection, induction, training and mentoring, and setting up project & customer interfaces. On an average I divide my time between customer relationship management, coaching, monitoring team performance, resourcing and a few administrative tasks.

What are a couple of challenges that you faced in Technical Writing and how did you address them?

One of the challenges in technical writing is to make the SMEs and the product managers understand the requirements of the end user. Convincing the SMEs to move from feature centric to task centric documentation is always a challenge.

Integrating the documentation life cycle with the product development life cycle is the other main challenge.  This has a direct bearing on the quality of our deliverables.

These challenges are nothing new and typical to technical writing in general.  In both cases, I believe this is an ongoing dialogue between the documentation and development teams. Constantly highlighting the value of usability in documentation goes a long way in ensuring that writing teams play an integral part in product development and help in creating highly usable documentation.  There is no short term fix for these challenges and developing a rapport with development teams is a critical success factor.

How do you unify the two approaches between DITA and Wiki publishing? Share with us in brief any implementation process of publishing DITA Content to Wiki.

We are seeing an increase in the number of tools that combine the ease of Wiki-based collaborative authoring and the transformational capability of DITA based modular documentation.  Citec has worked with customers to provide solutions that harness the power of DITA and the simplicity of Wiki based documentation.

One such approach would be to maintain customer documentation in DITA/XML, and export DITA topics to Wiki format for SME inputs, review and collaboration, where page templates containing a consistent “structure” can be set up to ease the transition of the content back to DITA. After language editing, only approved content can be pushed from the wiki to DITA/XML CMS, where the Technical Writer handles the publishing part. Working in wiki during the authoring phase can help in speeding up information gathering and technical reviews.

How do you see Technical Writing shaping up in the next five years?

These are very interesting times for the field of technical writing. With the increasing number of handheld computing devices and a younger target audience, the technical writing teams will need to gear up for collaborative authoring, managing newer and newer publishing formats and creating customized documentation that is tailored to individual users based on product configuration.  Our traditional way of working has given way to a more dynamic and agile approach. As we gear up for the needs of the customer, our roles are changing and we will soon  pay as much attention to managing content as we do to creating content.

Profile:

Sandhya Ravishankar joined Citec Information in 2005 and currently works as Operations Manager. After completing her engineering in Electronics & Communication,  Sandhya did a 4 year stint in a Telecom manufacturing company, before moving to technical documentation. Sandhya has a special interest in modular documentation and has worked in DITA based modular documentation environments in varied domains like Telecom, Manufacturing, and Power & Automation.

Possibly related articles:

1. Experts Ignite
2. Experts Ignite
3. Experts Ignite

Philip John and Sheena Lakshmi from the Dell team

PowerEdge R810 Hardware Owner’s Manual—The Award Winning Document at the 13^th Annual STC India Conference Competition

The Product

Dell PowerEdge R810 is a high-density rack server that combines advanced management capabilities with leading price-per-performance features. This product was selected as one of the winners in the 49th Annual R&D 100 Awards for the year 2011, by the R&D Magazine. The award acknowledges the 100 most technologically significant products introduced in the market by a wide cross-section of industries.

The Hardware Owner’s Manual

The Hardware Owner’s Manual is a one-stop hub to access system hardware information, such as supported configurations, setup instructions, system servicing, error interpretation, firmware information, and troubleshooting procedures.

The Approach

A lot of collective effort went into the development of the Hardware Owner’s Manual involving the documentation and the product development teams. Some of the significant factors that helped in completing this manual successfully are:

• Early start ― One of the key success factors for this effort was our early involvement with the development teams and consistent tracking of the product development effort. This gave us visibility into the larger picture as well as the nitty-gritty of the project.
• Initial preparations ― The initial inputs were gathered from the engineering specifications document and the prototype of the server. Being part of the project update meetings and discussions also helped us understand the product better.
• Early involvement of the editor ― The editor was involved early in the document development cycle, which benefitted the document development effort. Documentation aspects such as style, language, organization, readability, and usability were taken into consideration from the beginning.
• Internal reviews ―  The initial draft, which included the preliminary illustrations and procedures, was refined to include the internal team’s ideas and error fixes. This helped the engineering team to concentrate on the technical aspects.
• Continuous engagement with illustrators and the mechanical engineering team ― The writer worked in close coordination with the illustrators across the globe to develop the images for the assembling and dissembling procedures. In addition, the illustrators referred to the Pro-E files developed by the mechanical engineering team to ensure accuracy.
• Focused engineering reviews ― Drafts of complicated features were sent to the relevant SMEs  ahead of the schedule to minimize churn during the formal reviews.

The Challenges

Challenges were aplenty and the documentation team went through an intense phase of content iterations with short turnaround times. The main factors that contributed to such a situation were:

• Late changes in system features ― Major changes to hardware design and firmware updates deviating from the conceptual design had a cascading effect on multiple sections of the document. Analyzing the impact of the revised features within a shrinking timeline was a challenge.
• Re-designing illustrations ― A lot of effort went into communicating the revised illustration requirements to the illustrators to accommodate the last minute changes. This required multiple iterations of the illustrations based on discussions between the writer and the illustrator.
• Multiple opinions from multiple teams ― Opinions on the same feature from the product development team members at certain times stood as an impediment. These posed challenges to the documentation team while looking for the best alternative.

The Result

A document that is:

• Technically accurate, comprehensive, and customer-friendly and scored high on readability and usability.
• Recognized as the base for developing future customer documentation for products with similar complexities.
• Capable of assisting marketing efforts to boost the product sales in an extremely competitive market.
• One of the contributing factors in enhancing customer experience.

Possibly related articles:

1. Simulating Hardware
2. Publish-As-You-Write Model for Documentation

Manjula Kandula

Dolly, the world’s first cloned sheep was born on 5 July 1996. It was an epoch-making milestone in science and opened the door to understanding creation. Noted science journalist Gina Kolata broke the news nationally in The New York Times and was the first reporter to speak with Dr. Ian Wilmut, the embryologist who cloned Dolly.
Dolly lived a pampered existence at the Roslin Institute, Edinburgh, Scotland. She mated and produced normal offspring in the normal way, showing that such cloned animals can reproduce. When she was only six and a half years of age, she suffered from a tumor and had to be euthanized. This brings up a fundamental question. Can clones really be as healthy as naturally born animals? Scientists reason that Dolly died young, but then she lived indoors and didn´t have the typical life of a sheep. On the other hand, several clone mates of Dolly are over nine years of age and doing fine.
A discerning eye can see that there are two sides to the cloning story. It’s a story that any science journalist would love pick up to create eye-catching reports.
Science journalists play a pivotal role in society – they explain the how and why of important scientific advances. They often tailor esoteric knowledge in a manner that is intriguing to their readers.

Science writing and science journalism are often used interchangeably. Perhaps the key difference between these two related professions lies in the approach to science itself.

Science writers clearly and accurately describe interesting science in plain language. Science journalists get to the bottom of a story, to figure out what’s really going on behind the scenes, identify the main players, and see what the real “scoop” is.

Either way, simplifying science is a challenge because one cannot distort scientific facts and convey the wrong meaning to readers.

Whether one wants to take up science writing or science journalism, the bottom-line is the ability to write well. You need to have a knack of identifying good and contemporary topics, and have strong research skills. You need to organize your facts in a manner that tells the story precisely and succinctly. You might also want to include pictures and graphics to supplement the story telling.

While it is easy to grab the reader’s attention while reporting a sports event, science articles need more care to catch the reader’s eye. You need to have an intriguing ‘anchor’ or ‘peg’ in the beginning of your article. For example, in a health-related article, writers often use a case study (with fictitious names) as an anchor. Bringing up a case study makes the reader empathize with the ‘actors’ in the story.

Good headlines help catch the readers’ attention, so most newspapers spend a lot of time in phrasing the headline because it’s not merely the content of the article but also the headline that sells.

Subjects like health and medicine enjoy a constant interest while articles in physics often have niche readership. Astronomy has bursts of readership during events such as an eclipse or an asteroid sighting.
Science and ethics are also closely interlinked and this makes science reporting even more challenging. For example, the European Court of Justice has banned – on ethical grounds – the issuing of patents for embryonic stem cell research. The judgment is designed to prevent the commercial exploitation of discoveries, which involve the destruction of human embryos.
Good science writing depends less on sensationalizing science and more on reporting facts in an elegant manner.
To use a baker’s analogy, you can either hastily turn over a cake tin and crumble up your dessert or gently tip the tin over to uncover a beautiful cake. How you unravel your story does makes a difference, especially in science writing.

About the Author

Manjula Kandula is a documentation manager at Ariba, Bangalore. Prior to that, she has worked at VMware, Sun Microsystems and Hewlett Packard as manager and technical editor. She started her career in writing as a science journalist at Deccan Herald. She has a PhD in biochemistry from the Indian Institute of Science, Bangalore. Her hobbies are reading, listening to music and going for long nature walks.’

Possibly related articles:

1. Essential skills for Technical Writers in 2011

Anindita Basu

Do not repeat the text of the title in the first sentence of your topic.

When your topic gets pulled into search results, what is displayed is the title of the topic (in the form of a link) and the first few words in that topic.  If the first sentence of the topic uses the same words as the title, you are losing that much screen space, which you could have otherwise used to write an abstract for the topic.

Do a Find-Replace for words you know you misspell often

Running a spell-check is fine but it is easy for the automaton to miss the typos that, otherwise,  are valid words.  Here is an illustrative list of words that will always be missed by computerized spellchekers: sue (use), lick (click), filed (field).

Ensure that index entries point to no more than two topics

Anything more than two topics (or, pages) and the reader is confused about where to jump.  If you find an index entry with several possible jumps, turn the entries into more something that is more specific.

About the Author

Anindita Basu is an editor at IBM. She can be reached at anindita_basu@shortmail.com.

Acknowledgments: The comic strip was created at http://www.pixton.com/balance

Possibly related articles:

1. Writing Tips
2. DITA Writing Tips
3. Gone in Sixty Seconds?

Saurabh Kudesia

As an alumnus of Indian Institute of Management (IIM), Bangalore, what value additions are you bringing to technical communication?

Value addition means generating greater return on investment than the cost of the initial investment. Return on investment has two important aspects: bringing in more money (by increasing users’ satisfaction) or reducing costs (such as the cost of supporting customers, or inefficient processes). As writers, we should be aware that numbers represent an incomplete picture of our contribution and often we may have to go beyond traditional lines to get credit for value that we add to the organization. In an era of increasing cost consciousness, technical communicators are under ever-greater pressure to show just how we add value and how much value we add. Our goal should be to first prove the value of documentation to those interested in the bottom line and second make that value true. As managers, there are many things we can do to use the documentation to boost the bottom line:

• Look for duplicated efforts and bottlenecks that occur because of a lack of information and use documentation to reduce negative impacts arising out of them.
• Clearly demonstrate the benefits of documentation to your audience. Incomplete or inconsistent documentation presents an image to the client that the company is disorganized and not a good one with which to do business.
• Continuously solicit feedback and incorporate them in a timely manner to silence the critics. Show that you want to work with the other teams, not against each other.
• Use a central location for all documentation. Using a single-sourcing content management methodology across departments can reduce duplicated writing efforts in many areas, such as marketing, training, product management, sales, etc.

Not everyone in your organization will understand the value of the documentation all the time, but acknowledge these challenges as part of your job as a manager and never give up.

How do knowledge-based approaches help in designing and developing documentation?

A knowledge intensive development framework is more critical in the documentation design process and has been recognized as a solution to achieve competitive advantages in product development. Knowledge-based approaches provide access to the right knowledge and to continue doing business without a drop-off in performance. From the documentation perspective, knowledge-based approaches pave the way for component-based modular documentation that provides an effective means to realize a range of customer demands in support for mass customization. The process enables customization of documentation to satisfy various product variants to meet the specific market, business, and engineering needs, and results in an integrated modular documentation set with scenario specific knowledge support. A documentation family is thus reduced to a set of variables, features, or components (smaller, independent chunks of information) that remains constant in a product and can be maintained from release to release without losing its flexibility to manage increased product variety necessary for today’s market.

Knowledge-based approaches place an emphasis on how to set up rational documentation architecture to conduct family-based design, rather than design only a single document. The knowledge-based documentation development approach usually includes two main phases:

1.        Establishing appropriate documentation development and management platform.

2.       Customizing the platform into individual document variants to match product variation.

Essentially, this requires documentation set to be viewed as a group of related documents that share common features or component/subsystems description, and captures the information in a way that satisfy a variety of customer groups.

Knowledge-based approaches incorporate the concept of functional modularity from the product life cycle perspective to documentation and allow the design of document families by changing a small number of components or modules. It also provides access to document variety design, including representation, measurement and evaluation of document varieties. Thus, developing documents no longer remain confined to delivering information silos, but cater to ‘information variety’—a term that refers to flexible documents that meet the best balance of design modularity and component standardization.

Could you share a couple of best practices in documentation?

Today, technology has evolved into a complex social enterprise that both reflects and shapes the system’s values. We should always be conscious of underlying concepts that drives the domain and anticipate the effects of technology. Measuring domain complexity objectively is difficult. It is more of writer’s subjective experience of complexity that might be the consequence of the nature of the task in the specific situation, in relation to specific purpose, skill, competence and experience of the writer. This means that while one writer might experience a particular domain situation as complex, another might not.

Complexity is also a pre-condition for innovation and creativity. It gives us an excellent opportunity to be surprisingly creative in our writing adventures. It helps us apply the learning in one domain, under a particular situation, to another more or less similar situation and get the unanticipated results.

As writers, we should always be looking for opportunity to transform subject complexity into a challenge, something we can explore and experience, something we can attempt to master and in the process, make it easier for our readers to understand and master. While we may not be able to influence domain/subject complexity, we can always explore innovative ways to understand how the underlying philosophy and principles in one area might be commensurable in another field. Think about innovative ways to utilize your gained knowledge to penetrate into other domains. With perseverance and practice, you should be able to develop a mental knowledge framework that helps you connect seamlessly across different domains. If you are not already thinking of applying the learned concepts and principles in one domain to another, you are already on your way to creating multiple knowledge silos that never communicate to each other and will never help you succeed as a writer in multiple domains.

What should companies consider before investing in Help Authoring Tools and Content Management Systems?

Organizations are no longer creating a single document; they are creating content, and content is meant to be connected, used, and reused with no great assumptions about how and when. The premium is placed on how the content is connected to others rather than on how complete they are in themselves.
Content Management Systems (CMS) make your life easier by helping streamlining your business and keeping you out of the nuts and bolts. However, no authoring tool or CMS you create or buy will tell you what your organization should manage or why. You must perform proper ground research and formulate all the details before selecting or designing an appropriate system.

A good way of examining your organization’s CMS needs is to understand the type and scope of information problems that the staff or customer is facing. If you do not hear a lot of issues or worries that surround the core issues of content management, you should question the need for a CMS! In a nutshell, you need a CMS if your content collection, management, and publishing processes are too complex to manage informally. You can gauge the complexity of your content on the following parameters: the amount of existing and future content, the number of contributors contributing the content, the size and complexity of the contributed content, the amount of change that you expect in your content, the number or type of publication that you intend to create or edit, and the degree of personalization/redesigns required for your content.

What would be your advice to the technical writers who are planning to move to the documentation manager role?

Project management in competitive business is rarely a job for the faint-hearted who lack confidence in their ability to learn and communicate what they have learned to others. A good manager is aware of the need to keep developing management skills on a continuous basis. If you are an effective communicator who has vision, enjoys a leadership role and working with people, and adept at monitoring project details and controlling change, documentation management is a job for you.

If your goal is to be a documentation manager, it is not enough to be a good writer or editor or even to like working with people. You must prepare yourself to play multiple roles in the organization, with responsibilities to manage the content of the projects, as well as manage the people and other resources necessary to perform the project. Your ability to communicate with team members, customers, senior management, and managers in peer organization becomes more important. You must know how to estimate and allocate time and cost. You should develop a thorough understanding and empathy for the document development process. You should be ready to engage yourself in the development process as you work side by side with your team members, and should be able to guide your team members to produce appropriate levels of quality that meets customer requirements. As aspiring project managers, you should first start developing the understanding of the needs of your team members, customers and your organization. Next, understand your corporate priorities and take initiative to get things accomplished.

If you want to get on the management ladder, then look for opportunities where you can practice and demonstrate your management skills. One way to gain expertise is to perform tasks so you can develop your skills, and the other way is to enroll on management programmes and training.

Also, beware that owing to so many diverse responsibilities, project managers tend to find themselves in the middle—pulled in a variety of directions by compelling and often contradictory forces. The most challenging part of any managerial role is managing people, and often a manager is responsible for a large number of employees. Developing your people management skills is a task that you should never ignore at any stage of your career. Additionally, look for ways to broaden your skills in different management functions. For instance, if you work in development, consider spending some time with the QA, Sales, or customer services department. This will help you improve your ability to view problems in different perspectives and help you handle issues between the departments. Look for opportunities to work on inter departmental teams to sharpen your management skills and develop a broad range of knowledge.

And before you think you are ready to apply for a manager’s role, pack a bag full of patience and curiosity—something you will probably find important to have when you reach your destination.

About the Author

Saurabh is currently with Nokia Siemens Networks, Bangalore as Customer Documentation Manager. He has an experience of over a decade managing globally distributed documentation teams and providing documentation services for a variety of domains. He has managed more than 120 documentation projects and implemented over a dozen medium/large size knowledge bases for IT, Information Technology Enable Service (ITES), Business Process Outsourcing (BPO), and product-based companies/clients globally.

He was member of the panel of Expert Evaluators for revising ISO/IEC 25612 standards and made significant contribution to the Unicode Common Locale Data Repository (UCLDR) project. He co-founded, and later served as Editor-in-Chief of, KnowGenesis International Journal for Technical Communication (IJTC). He also provided his services as Associate Editor to Directives, a newsletter published by the Society of Technical Communication (STC)’s Management Special Interest Group (SIG). He has contributed multiple works in international research publications and conferences and has conducted several workshops globally in subjects such as Content Management, Knowledge Management and Documentation Process improvements.

In addition to holding an engineering degree in Electronics, Saurabh is a Certified Scrum Master (CSM) and an alumnus of Symbiosis Institute Pune and Indian Institute of Management (IIM) Bangalore. You can contact him at saurabhkudesia@gmail.com .

Possibly related articles:

1. Experts Ignite
2. Experts Ignite
3. Experts Ignite

Vol XIII, Issue 5

We are back with yet another edition of INDUS, STC India’s newsletter. The INDUS team would like to thank all who have contributed to this edition. We hope you will enjoy reading the articles in this edition.
Once again, we request you to send your feedback to us. We also request you to send us your ideas for the next edition of the newsletter.

Kit Brown-Hoekstra writes about how the documentation and the translation processes affect each other and how they can be integrated. Aisoorya Vijayakumar explains how an effective workflow helps the technical writers.

Experts Ignite this time features Saurabh Kudesia, Customer Documentation Manager with Nokia Siemens Networks, Bangalore. Saurabh shares his experience and ideas on knowledge-based approaches to documentation, best practices, and CMS, and provides tips to aspiring documentation managers. Makarand  Pandit has a few useful FAQs on Digital Rights Management (DRM).

Bindu Nayar describes the advantages of Publish-As-You-Write documentation model to avoid the chaos and confusion prior to the release deadline and Anindita Basu shares more invaluable tips on writing. In Prez Talk, Rajdeep Gupta talks about the much-awaited 13th STC Annual Conference to be held in Chennai.

As always, we have a few STC Announcements for you.
- Anupama Gummaraju and Sreeraj Nair

If you wish to write for INDUS, please read the authoring guidelines first, and then send in your article ideas to the editors.

Possibly related articles:

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

By Aisoorya Vijayakumar

I can almost read for certain the thought that runs on your mind as you are reading this – “Alright! Here’s another nagging post on how I need to start and get on with my documentation…!” I would have empathized, and on a sunny day, even applauded you on guessing it right, had I not had the home advantage of knowing that this is not another run-of-the-mill post on the much-beaten-to-death topic on how one should do authoring.

If you are a writer well on to the second half of your decade-old technical writing career, let’s take one moment to recall those initial days of frustration and struggle when you wished for a miracle to fall through the roof and help you get a grip on how and where to begin. We all have been through those moments of cluelessness where we ended up with nightmares of distressed customers chasing us with cannon balls. Now, having got a reasonable idea on which potholes we need to look out for and which potential demons we need to slay, we take on our writing duties with more confidence.

But if you ever happen to notice the face of a newbie who has joined your team, and observe the collage of expressions he or she seems to give, you would be able to notice his or her haggard emotions ranging from confusion to absolute dread. This post is more of a ready reckoner intended for any person with newly bestowed authoring duties.

Authoring invariably tends to flop because of lack of proper homework. With all the enthusiasm reserved for a young tender mind, when a writer holds his or her breath and takes a plunge into the deep sea of documentation, with no proper deep-sea diving gear, the sea would turn deadly in no time and would choke the life out of the writer. Taking a moment to learn the steps involved in the workflow of authoring a well-churned-out document would help immensely in the long.

Setting Sail

Points with which we begin our authoring journey…

Let’s say you and your friend are off on a long safari trip in Amazon. While you believe in just backpacking, throwing darts on a jungle map, and stopping at every village that the dart lands on, your friend believes in making a study of the place, being well-informed on local cultures, understanding about the indigenous wildlife, and then making the trip loaded with reserves for all possible emergencies. Given, your method may look tempting to begin with – no groundwork, no worries! But if you reflect on this carefully, you cannot deny the fact that your friend has probably more chances of surviving the dangers in the jungle, while you might probably end up as breakfast stew for a local tribe, or the dinner dessert for a lurking lion. While getting into the job on an impulse may suit some vocations, we need to be clear on the point that documentation is not one of them. Here, it pays to be prepared. Hence, before you begin authoring, just keep an eye on these following points.

Audience Analysis

Understanding your audience is key to your success as a technical writer. Not really knowing who you are writing for, makes you vulnerable and prone to criticism or indifference. Keep in mind the following:

1. The audience preferences tend to be startlingly varied, based on their geographical locations, language use, heritage, culture, customs, beliefs, and so on.
2. Remember that your bonding with the audience does not end with the authoring phase.
3. Keep a tab constantly on how comfortable they are with your documentation and how better they would like it to be. Most organizations have customer forums and conference calls where the customers get to express not just their delight, but also their angst if any, on the products and the end user documentation. Start using such forums to your advantage and your document is already on the winning path.

Choosing and Customizing Your Authoring Environment

Never underestimate the importance of doing a good research on the authoring tools available in the market. This link provides a comprehensive insight into the various Help Authoring Tools (HATs) available. There is a myriad of authoring tools, with the number increasing every minute of every hour, with diverse uses. So, if a single-source, multiple-format-output need is what you have, choose an appropriate tool, instead of going for a single output tool and then spending further money on converting that output into other formats.

It is equally important to tailor your authoring environment to suit your need. Think of the authoring tool as a sweater. The sweater is not going to keep you warm and snug until it is the right fit. Making sure that your tool fits your needs aptly, is as important as this. If you intend to use an XML authoring environment, this publication by the Wisconsin chapter of the Society for Technical Communications (STC) will be a handy aide.

Progressing Towards the Horizon

Strengthening and enhancing authoring efficiency…

Now that your armor is ready for the battle, you are all set to take the firing head on. You just need to remember a few basic protocols. And trust me, following a protocol is no menial task. It comes in very handy. Even army folks memorize their protocols and commands, arguably to ensure they don’t misinterpret a command that the captain shouts and end up butting their rifles on the captain’s head instead of the enemy’s.

Information Gathering

How do you know where to begin and where to end your document? How do you get enlightened on what the scope is? How do you know the type of document that your project needs? How do you know whom you need to turn to for technical information? You won’t know any of this until you gather some elementary information on the project requirements. Do not wait for the information to reach you on its own. Take some initiatives, check your technical teams for spec files or design documents, get started on understanding the logic behind the product, pour some energy into the project, and see the difference it makes to those involved.

Gain a Good Standing on the Technical Know-how

Yes, your technical teams would give you knowledge sessions on the product. Yes, your SMEs would always be there to respond to your questions on the product. And of course, yes, you would always have the technical spec documents to fall back on, for any dearth of information. But none of this can compensate for the rich understanding you’d gain, by playing around with the product yourself. If you are documenting for software application, talk to your engineering team, get yourself access to the application and then start using the application. Ask yourself questions at each step on what you are struggling with, and what kind of information in a document would help you with that particular problem. This makes your documentation technically crisp, in turn reducing the time and effort you would ideally spend for reviews.

Set Contribution Expectations Clear with the Technical Team

It is very important to let your technical team – developers and testers – know what help you’d need from them to help you write better. If you were expecting any specific technical inputs, it would be good to give them a set of precise questions for which they can frame answers. You also need to let them be prepared with their post-authoring review duties. Don’t spring a surprise on them one fine morning expecting them to review a 50-page document in a day. Let them know that you’d send out information in manageable chunks, as and when you author them, and give them a sample of the review comments, you are expecting. Give them considerable time to do a detailed review and mail you their comments or talk to you about their comments over a review meeting.

Flagging the Destination

Winding up and analyzing end results…

Once the document is ready, do resist your urge to share the document with the reviewers and editors right away. A very important, but often overlooked step in authoring is self-validation of your documentation. Do a reverse review (from the last page to the first) to check for the spelling and a forward review (from the first page to the last) to check for improper information flow and sentence construction.

Once you pack your document off for reviews, and all the pieces are in place in the puzzle, jot down your learnings and key take-aways while you await review comments.

Some points to be penned down that may come in very useful later on, could be:

1. Get key terms ready for an index or a glossary if your document would have one.
2. Document important issues you faced with the authoring tool and their workaround solutions.



3. List down points of contact from the technical team and their contact details. This would be of good use when you transition the project.

…And there you go! You are done with authoring a document as effectively as anyone can and you can pat yourself for a job well handled.

Note: All graphics have been sourced from Novell. Copyright infringements are prohibited.

About the Author

Aisoorya Vijayakumar, a Lead Technical Writer with Novell, has close to six years of experience in the field of technical communication. She has worked extensively on technical learning modules and end-user product documentation. In addition to her primary documentation responsibilities, she takes care of patch release documentation management for her team at Novell.

Possibly related articles:

1. Being a Contract Technical Writer
2. Story of an Ungadgetted Technical Writer

By Bindu Nayar

A Reality Check

So at what stage in the Software Development Life Cycle (SDLC) does documentation get done? If you said “right at the start”, then your organization is unique. The fact is that no matter how much we propound the benefits documentation presents to our customers and the organization, in reality, it is probably the last thing on the minds of the engineering team – probably rightly so, as in most cases, without code, there can be no documentation. But most of the time, reviews are done only towards the end of the release. This is of course not by choice, but due to the fact that documentation in most cases gets generated only after the coding is done.

Dealing With Change

Yes, you have all the bells and whistles—   the effort estimates, the plan and the schedule.  You have even convinced the engineering manager to spare the developer’s time for the review cycles. But what typically happens is that between the time you write and the document gets reviewed, what you have already written seems a bit different from the actual behavior of the software. While most of the time the changes can be subtle, in some cases it can be drastically different.

This may lead to a lot of situations where last-minute rushed reviews are done and corrective measures are taken to ensure that the documentation aligns with the workings of the software. When it comes to such fire-fighting situations, many a time crucial and critical details are missed out and this may lead to lot of complications and inconveniences for the customer.

Have you wondered how good it would be if there exists a system that publishes your documents as you write and you can get the reviews done in an online manner?

A system that will help you provide a preview of your documentation to your reviewers, thus aiding in a more collaborative and effective review system.

Analysing the Need

Do you really have a need to implement a system like this? Ask yourself these questions to ascertain if you really need to implement a Publish-As-You-Write system.

1. Does the product/project you are working on have a long development cycle and is expected to go through a lot of churn before it is released to the customer?
2. Do you have frequent code drops that include documentation as a deliverable?
3. Do you have multiple reviewers whose approvals are required for the documentation to be certified as done?
4. Have there been instances when the final content that got shipped with the release greatly differed from what you had initially written?

If you have answered “Yes” to most of the questions above, then a system like this will help you iron out the operational issues associated with getting reviews done on time and in an effective manner.

Principles of the Publish-As-You-Write Model

The concept of publish-as-you-write is in reality, a simple process that works on the principle of What, Where and When.

The 3 W’s

1. What:  Identifying “What” has changed
2. Where : Determining the location “Where” the changes should be published.
3. When : Timing the frequency to determine “When” the changes should be picked up.

Let’s see how you can implement a system like this without much effort and cost.

The Inner Workings of a Publish-As-You-Write Model

1.   Central Repository of Source Files

Having your source files version controlled is a must-have in today’s world considering the rapid pace of development and the need to work on parallel releases/projects at the same time. But if you do not have a version control system in place, do not worry.

To implement a publish-as-you-write model, all you need is a central repository of files.  The format of the files also doesn’t matter—be it Word, Frame or Epic Editor.

2.   Identifying and Processing What Has Changed

This part of the process involves two steps:

1. Watch
2. Pick

Watch

This step is to have a machine that will double up as a build server. This server will run scripts that will “watch” the central repository to locate files that have undergone any change. You can have a Windows/Mac/Linux machines to act as a build server.

Pick

To “pick” up files that have changed, you will need to write scripts that can identify the change in timestamp details.You can pick up any scripting language like Perl, Ruby, Phython, or Java.

3.   Packaging the Content

If the files you have submitted to the repository is in a format like XML, you will need further processing to make it in consumable. For instance you will need to use content transformation methods like XSLT, XSLFO to get content into popular formats like HTML and PDF.

If you are using a Word processing software like MS Word and are planning to give your customers documents that are in PDF format, all that you need are drivers that will generate the PDF for you. In such a situation, apart from the free/licensed drivers you will not require any further content regeneration tools or systems.

At this stage of the process, your files are in a format like HTML or PDF and this is what kick-starts the process of publish-as-you-write.

4.   Publishing the Documents

The files that have changed now need to be pushed to a location where they can be viewed for the review purposes. For this you will need a web server that can host the content.

If your company  has an open publishing policy, all that you need to do is set up the web server framework to list all your documents for review.

If your production environment demands that you share your documents with your clients (outside your company network) for review, you can set access control. Just share the login credentials with them and they can access and review your guides.

5.   Timing the Builds

How often do you want the builds to happen?  You can make it as frequent as every two hours or have it generate a build at the end of the day. To make the process automatic, include the frequency parameter in your scripts to do the fetching and generating at predetermined intervals.

Conclusion:

The Publish-As-You-Write system is a simple and effective means to avoid fire-fighting situations that typically happens in most of the documentation development scenarios.

As the document creation and review are cyclical, it helps in better operational alignment with the project cycles. This in turn reduces the load on your SME’s or stakeholders to do last-minute reviews and corrections. So with your reviews done and the documentation live for everybody to see, you have managed to check a documentation deliverable off the list of to-do’s. When its time for the release all that is required is package it or publish it to a live site.

The interesting and appealing part of the autobuild system is that you do not need great technical expertise to set up a system like this. Your Production Specialist can help you get a system like this in place. But, if you do not have the luxury of an in-house Production specialist, engage with your development engineer to get the scripting done. After the scripts are done, its all about just scheduling the scripts and sitting back and watching what you write, come online in a matter of hours.

Bindu Nayar is a Lead Technical Writer with over 11 years experience in the technical writing field with core experience in protocol and developer documentation. In addition to primary role of authoring, she is currently involved in project management activities at Novell.

Possibly related articles:

1. Write-up: PowerEdge R810 Hardware Owner’s Manual
2. Applying Lean Six-Sigma Principles to Documentation
3. When Worlds Collide: Understanding How Documentation and Translation Processes Affect Each Other

By Makarand  Pandit

What exactly is Digital Rights Management or DRM? Why is it needed?

Digital Rights Management (DRM) is a collective term. It refers to access control technologies for managing rights of content in digital form.

Internet makes it easy to publish and distribute content. Different laws in different geographies make it difficult to control access and distribution of content. The estimated loss to content owners, resulting out of unauthorized distribution and sharing, is estimated to be up to US$5 billion every year (reference Wikipedia.)

Who uses DRM?

DRM is used by producers, publishers, copyright holders, and even distributors of the content. This includes publishers, writers/authors, and even companies that want to restrict access to content or its unauthorized duplication.

Does DRM apply to only books?

Nope! DRM can be used for text, images, audio, video, and other types of files.

What are the advantages of DRM?

• Publish online
• Distribute online
• Protect originality
• Claim copyrights
• Control distribution
• Activate licenses online
• Issue single/multiple licenses
• Invoke/deactivate licenses, if required
• Reduce cost by issuing time-bound license (content-as-a-service)
• Use Content Management Servers (like Adobe Content Server) for enterprise level content access restrictions

How does the system work?

DRM enforces control through various means. This includes one or more of the following:

• Authenticating the authorized user through a mandatory registration process
• Restricting number of copies that can be made
• Protecting access to the content (read-only access, copy protect, print protect, access only on limited number/types of devices)
• Allowing time-bound access to the content (restricted by date, restricted by number of times a document can be opened)

What is the relationship between DRM and eBook Readers?

To be effective, DRM has to be jointly enforced by hardware (devices used to access the content) and software (file types used to store the content.) The hardware has to enable the protection achieved through the software.

Most eBook readers (dedicated hardware devices) support one or more DRM technologies. Many eBook reader manufacturers (Amazon, Sony, and so on) have developed their own DRM technology. Some adopt to specific DRM Technology or specific file formats. Many smart phones also act as eBook readers after installing some plug-ins/apps.

Is PDF an eBook format? What are the other eBook formats used?

Yes, because of the access restriction features that it provides PDF can be categorized as an eBook format. It is also supported by most eBook readers. There are many other file formats though including

• .epub – Created by International Digital Publishing Forum
• .lit – Created by Microsoft
• .azw – Created by Amazon

The type and level of protection can differ in each. There are many other formats used for other types of content, for example, entertainment content.

What are the limitations of DRM?

• Most access control techniques are algorithm-based. This restricts subjective opinion (that can be exercised by human brain.)
• Some of the features can be construed to be against the fair-use-of-content.
• Different publishers and device makers follow different techniques to suit their own content/devices. This is not in the best interest of the consumer.
• There are just too many techniques and technologies available, and a worldwide standard has not yet been established.
• Many issues like fonts in regional languages can create challenges on some devices (through this problem cannot be attributed to DRM alone.)
• Some technologies permit remote disabling (or even deletion) of content. This is perceived to be against individual freedom. Organizations like Free Software Foundation are objecting to such features.
• Some DRM technologies can trace the original “registered buyer” of the content or can tag the “credit/debit card details” of original purchase, as a means to discourage distribution of the content. This is seen as compromising identity and privacy.

How are Technical Communicators related to DRM?

• Enhance your brand and increase your reach by providing eBooks.
• Publish documents in eBook formats and with different levels of access restrictions.
• Package text, audio, and video as a part of one eBook.
• Generate revenues through innovative packaging and distribution of content (including knowledgebase books like tutorials, training booklets, and so on.) Take it as Content-as-a-Service (CaaS) revenue model.

Where can one get more information?

• Wikipedia
• International Digital Publishing Forum (IDPF)
• iTune Store
• Free Software Foundation

Note: The author will be conducting a workshop on DRM and eBooks on 1 December 2011 at STC India’s 2011 Chennai Annual Conference.

About the Author

Mak Pandit is Managing Director of Technowrites Pvt. Ltd. He is an experienced writer and trainer with over 17 years of professional experience. Mak is a senior member of STC and is serving as Pune City Representative for STC India. His latest creation www.contentmarket.in is a portal dedicated to the advancement of content creation and marketing in the Indian subcontinent. Mak can be reached at mak@technowrites.com.

Possibly related articles:

1. Automation of Documentation Submittals via HP Quick Test Professional

By Kit Brown-Hoekstra

Companies that successfully integrate translation into the documentation and product development process reap the financial benefits of simultaneous global releases, high quality products that meet the needs of all their customers, regardless of locale, and improved perception of customer service. Such integration also requires the localization/translation vendor to take a long-term view toward its client relationships because, while integration results in short-term loss of revenue on a project, the overall budget for localization doesn’t typically go down. Instead, those short-term savings go toward adding languages, improving the product’s internationalization, localizing marketing, or other initiatives that improve the company’s global presence, all of which represent revenue opportunities for the savvy localization vendor.
Regardless of your role in the translation process (content creator, translator, project manager, etc.), you need to understand how both the documentation process and the translation process affect each other, where the problems occur, and how to integrate the two so that the company can meet its goals in the global marketplace.

Documentation Process

Quality translation really begins with content creation and the processes that support it, as well as the degree to which the company incorporates internationalization into the product development cycle and its strategic planning. There are essentially four levels of internationalization in a company, and it’s important to understand that each level both affects and is affected by the others:

• Organizational
• Process
• Product
• Documentation

Companies vary greatly in their global maturity at each of these levels, but the most mature ones integrate internationalization not only into the product development cycle, but also into their overall strategic planning and marketing. The company’s global maturity level will give you an idea of how difficult it will be for the client localization manager or documentation manager to effect change, and helps you understand the company’s cultural milieu. Companies that have globalization and internationalization built into their overall strategic plan will be more open to suggestions and better able to facilitate changes at all levels of the organization.
While most documentation teams have little control over the overall corporate strategy and corporate level processes, they often significantly influence the product development, and control the documentation process.
The documentation process is one of creation and iteration. The documentation team typically is responsible for every aspect of the documentation, from researching and participating in product development team meetings to developing templates, style guides, and glossaries to content creation and management to publishing.

Documentation teams must be able to understand both the technical staff and the audience, to deal well with ambiguity, to distill reams of technical data and specifications into usable and useful information, and often to test the usability of both the product and the documentation. Technical content creation is essentially a translation process as many users don’t speak geek and many techies have difficulty communicating at a level that is comfortable for non-techies. The team also must frequently deal with multiple, shifting priorities while still meeting deadlines (documentation is almost never allowed to hold up a product release).
Unfortunately, the translation/localization process is a “black box” for most documentation teams, and this lack of insight can cause issues with both the quality of the source documentation and the translations, particularly for companies that have implemented content management without fully integrating the translation team and process into the workflow. Taking the time to educate the documentation team on translation and localization issues can significantly improve the product’s global appeal and marketability. In addition, the earlier an issue is caught in the design process, the less expensive it is to fix (and the more likely that the fix will get made).

Translation Process

Translation, the act of taking content in one language and transferring it to another, is only part of the process for making a product and documentation set ready for a new language market. Good translators must not only speak both the source and target languages fluently, they must also understand the industry and products that they are translating the content for. Because they are native speakers of the target language, they also usually have native understanding of the target culture. In addition to the actual translation and editing process, the translation/localization team must ensure that the content is culturally appropriate and make adjustments where necessary.
The localization/translation team is also typically responsible for desktop publishing for print and engineering output for electronic media. And, the team must work closely with the client’s designated in-country reviewers, who might or might not have formal language or product training.
Translation and localization are acts of transference rather than development. The translation of the content is usually separated from the desktop publishing and engineering functions, and performed by different sub-teams. Because of this separation, good project management is critical to ensure that each functional group understands how its work affects the other team members.

One of the biggest challenges for translation/localization teams is that the translation tends to be pushed to the very end of the product release cycle and, if deadlines aren’t met, can cost companies millions of dollars in delayed releases. (Most countries’ regulations demand local language products, particularly for products that involve public safety, such as heavy equipment or medical devices.)

Working Together Without Colliding

Simultaneous releases are de rigueur for most products and industries, which means that translation and localization must become more fully integrated into the documentation process. This integration requires that both the company and the translation/localization vendor have a good relationship with each other and have a solid understanding of each other’s existing processes.
Several aspects of both the documentation and localization processes can be divorced from individual projects and assigned to senior team members who work closely with their counterparts:

• Terminology management: Create a sub-team that includes a representative from the documentation, translation, and development teams, as well as the in-country reviewers. When done as an ongoing activity, and especially when new products are developed, you can ensure more consistency throughout the product, documentation, marketing, and language products. The approved terms can be loaded into the translation memories early in the project and, for software projects, used in tests of the user interface.
• Style guide and template review and internationalization: Desktop publishing and engineering are often the largest costs in a translation project. By ensuring that the templates work with all languages, you can significantly reduce problems and overtime costs at the end of a project. Better yet, automating the publishing by using a content management system and structured authoring, saves costs and enables you to more effectively focus your resources on the quality of the content itself. (Cautionary note here: It takes significant effort to move to content management and structured authoring and doing so is not a panacea, so be sure to perform a cost/benefit analysis before leaping in.)
• Periodic content and process audits for internationalization and translation issues: These audits help you identify appropriate metrics, identify what you are doing well, and show you where there is room for improvement. When done consistently, the audits help you to prioritize your efforts, and give you the information you need to make sound business decisions.
• Integration of internationalization tasks into the fabric of every process, making it indistinguishable from best practices: Internationalization is, ideally, not a separate process, but is built into the very design of the products, strategic planning and cultural milieu. It’s much easier to design something that considers global needs, than it is to retrofit it later. It takes time to build the initial understanding and shift the corporate culture, and the process is ongoing as the teams reach new levels of knowledge and understanding. Once that integration occurs, however, companies begin to reap the rewards in terms of faster times to market, fewer cultural issues, improved customer service, and potentially, larger market share.

With integrated documentation and translation processes, you can also move some translation tasks earlier in the development process, where they can save significant costs. This activities include pseudo-translations, where you test the user interface to ensure that field labels and other elements fit properly, and pre-translations, where you run a draft in the source language through the translation memories to identify potential issues with the content. For example, a lot of 90-95% matches might indicate that preferential editorial changes are being made to previously translated content, or that content is being rewritten instead of re-used.

In addition, each team can improve integration by doing the following.

On the development side:

• Involve the localization project manager early in the product development process. This early involvement will help the localization project manager allocate resources and will enable them to identify areas where the translation team can contribute throughout the development cycle.
• Train team members on best practices. Improving the documentation for translation not only helps the customer who uses the translated products, it also improves usability and consistency of the source product.
• Establish effective editing, change management, and in-country review processes. Editing best practices are vital. Translation is very much a “garbage in, garbage out” process. The higher the quality of the source content, the better the translation will be. Change management allows you to be more proactive about how and when you submit changes to translation. If a project is already in post-editing or desktop publishing when you make the change, it will cost a lot more than if the content is just being started. In-country reviewers can completely derail the process because the translators depend on them for QA approval. Ensuring that the reviewers are trained in both the products, are native speakers of the target language, and that the review is part of their job description will help facilitate a smoother process.
• Communicate regularly and proactively with the localization project manager. You should have primary and secondary points of contact to act as liaisons with the translation team. If something comes up in a project meeting that affects the documentation that means it also affects translation.
• Consider modularizing your documentation, and implementing a content management (CMS) workflow. Modularizing the content enables you to send the content in chunks to the localization vendor, starting with the most stable content. Also, if you are using a CMS, you can send only the content that’s changed to the translation team, automate the publishing, and modify the translation QA process to ensure that the output is correct. The business case for each company will be different, but you could potentially save over 20% of your localization costs by implementing an effective workflow.

On the localization side:

• Communicate proactively with the client. If the client is consistently submitting problematic source content, tell them. Work with the documentation manager to train the team. Educate the client on what you need from them to be successful. Let them know the financial considerations for their decisions, but phrase it in a way that lets them know you are looking out for their best interests. For example, “We can certainly do X; the cost is Y. I suggest Z, which will cost less and still do what you need.”
• Establish primary and secondary contacts with the client team. You need to establish a rapport and habit of regular interaction with the client. Doing so helps you find out earlier of impacts to the translation process, and facilitates the project management.
• Review the templates, terminology, style guides, and so on early in the project. Provide the feedback early. If you wait until you are doing the translation or the desktop publishing, it’s too late. The documentation team has moved on to other projects by then, or is scrambling to document the latest feature that got added at the last minute.
• Offer to train the documentation team on how to write for translation. Such workshops help the documentation team see how their job affects the company’s bottom line. In most cases, your suggestions will require only a slight change in the way the documentation team works and will save significant localization costs. Take graphics for example. Simply removing the text from the graphics and using a legend could save the company thousands of dollars every project. In this example, if one graphic costs $50 to create, you have 100 graphics being translated into 20 languages, all of which need to be reworked to accommodate the text, that’s $100,000. In another example, one error in the source help content might cost $50 to fix. If you are translating into 20 languages and don’t catch the error in the source, that one error costs $1000 to fix (doesn’t sound like much until you multiply that $1000 by every error that gets missed in the source and fixed during translation).

From a technical and process standpoint, this integration is relatively simple, though, as with any major change, it can be difficult to get the initial buy-in and overcome inertia.
It’s a good idea to start with a pilot project staffed by innovative, motivated, and open-minded team members who understand the business reasons for integrating the translation and documentation processes, as well as having the technical skills to pull it off. Pilot projects allow you to work out any kinks and to set up metrics before changing everyone over to the new processes.

Conclusion

Understanding how documentation and translation each affect the quality of the other enables you to identify ways to integrate the processes to improve quality, while reducing costs and time to market. Effective content management and workflow facilitate this integration. With integration, it becomes even more important to nurture your relationships between the documentation and translation teams.

Note: This article was first published in Multilingual (Dec 2010), www.multilingual.com. It is reprinted here with permission.

About the Author

Kit Brown-Hoekstra, Principal of Comgenesis, LLC, is an Associate Fellow for STC, speaks regularly at conferences worldwide, and has authored many articles on a variety of technical communication and localization topics. She also coauthored (with Brenda Huettner and Char James-Tanny) the book Managing Virtual Teams: Getting the Most from Wikis, Blogs, and Other Collaborative Tools. Comgenesis, LLC provides consulting and training on internationalization, content strategy, process improvement, content audits, project management, and technical writing/editing. (This article is based on her training session from the Localization Institute’s Localization Project Manager Certificate Workshop, presented in St. Louis in 2008).

Possibly related articles:

1. Publish-As-You-Write Model for Documentation
2. Working with Cross-Cultural Documentation Teams
3. Applying Lean Six-Sigma Principles to Documentation

• The 2011 Community Achievement Award Guidelines and applications are now available. SIGs, Chapters, and Student Chapters are all eligible to apply for the Community Achievement Awards. There are three levels of recognition: Merit, Excellence, and Distinction. Applications and supporting materials are due 23 January 2012. Read more about CAAs here.
• Throughout 2011, Adobe is celebrating anniversaries of its flagship technical communication products, FrameMaker and RoboHelp. The celebrations on 13 November is in Austin, Texas, with a series of great speakers and a workshop on distributing and monetizing eBook content, besides many networking opportunities. Read the details about the event and free registration here.
• See a listing of November community events here. Many are virtual events and members can attend them online.
• To help community leaders run vibrant and active communities, STC Board is focusing on increasing the community services that are provided by the Community Affairs Committee (CAC). A complete list of such services is available here.
• 2012 membership is open! With the new MySTC Network, connecting and collaborating with colleagues is even easier than ever before. Multiple categories and discount schemes include the new TC professional, lower rate for SIG value packages, more free education with membership, and member get a member. Read more details here.

Possibly related articles:

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

It gives me immense pleasure to invite all of you to attend the 13^th STC India Annual Conference in Chennai on December 1, 2 and 3. Registrations for the much-awaited annual conference have started. This year’s agenda has been created with high precision, taking into account the feedback we received on the past STC India conferences. Our judges have painstakingly chosen papers that show the promise to serve your various knowledge needs effectively. No surprise, this year’s agenda covers topics that have never or rarely been presented in the past STC India conferences.

Please visit the following link to register for the conference:

http://www.stc-india.org/conferences/2011/?page_id=6

We have six pre-conference workshops that will provide training in topics ranging from Project Management to S1000D. The tools workshops will be on Author-it, FrameMaker and RoboHelp; these will be hands-on sessions with computers. We are planning the logistics requirements accordingly. Participation certificates will be issued to the attendees after the completion of the pre-conference workshops.

We will have the distinguished journalist and ace presenter of NDTV Hindu,  Sanjay Pinto, as the conference chief guest. Sanjay was the Bureau Chief of NDTV 24×7 before taking on the editorial mantle of NDTV-Hindu. As a news hound, Sanjay has over the last decade and a half covered every possible beat:  Politics, Courts, Crime, Sports, Entertainment, Business & Environment. Sanjay will be addressing the gathering on December 2 on Communication Ethics and its role in our society.

The main conference days will witness 34 presentations by seasoned technical communication professionals. A couple of the topics that we will get a chance to listen include user interface design, documentation for cloud,  managing localization in Author-it, publishing DITA content to Wiki, collaboration with customer support, and so on. In addition, we will have two panel discussions.

On December 2, Jaya Choudhary will moderate a panel discussion – Is the increasing advent of never ending list of tools decreasing the growth of technical writers. The following day Gyanesh Talwar and Nandini Gupta will moderate a panel discussion on Creating Online Certification Exam. This discussion will try to explore some of the questions like setting up exam objectives and deciding their weight and format and level of difficulty of questions.

A vote of thanks to all the speakers who have sent us their proposals. We received close to 80 proposals this year. We expect the same enthusiasm in the following years. Last but not the least, a big thank to you our conference sponsors- Adobe, Author-it Corporation, Citec, Contented, Madcap, Vestas, Oracle, Black & White, Collargroup and many others. Keep supporting us!

I have thoroughly enjoyed the previous year’s conference, and I am sure you must have done the same. The STC India Chapter is looking forward to meet all of you shortly, and I am sure you would love to take advantage of the professional development on offer.

See you at the 13th Annual Conference.

Possibly related articles:

1. Prez Talk
2. Prez Talk
3. Prez Talk

- Meghashri Dalvi

A lot has already been said about SMEs and their critical role in delivering user assistance on time and accurately. Most of the technical communicators will tell you that quite often their outlook and that of the SMEs differ vastly,and almost always their priorities seem to be diametrically opposite. Then is it possible at all to work well with SMEs?

The key lies in nurturing a long and strong relationship with the SMEs rather than just reaching out to them near the release date. And there you can use one of the simplest principles of a successful relationship – communicating by Behavioral Styles.

According to Dr. Tony Alessandra (founder of The Platinum Rule) the behavioral preferences of individuals can be classified into four basic styles: Director, Socializer, Relater, and Thinker. Each person has a mix of these styles, but there is always a dominant style with which that person behaves and communicates.

The typical characteristics of each style can be easily identified:

Director:

• Prefers direct approach, control, freedom, action, and results.
• Rejects openness, wastage of time, excessive display of emotions, and unsolicited advice.
• Often decides and works alone.

Socializer:

• Prefers direct approach, openness, group activities, camaraderie, and spontaneity.
• Avoids solitude, urgency, and concentration.
• Is an excellent team player, but may not deliver results. Direct and Open

Relater:

• Prefers indirect approach, openness, close relations, listening, and security.
• Avoids decision-making, conflicts, big picture, and self-reliance.
• May need counseling in weak areas.

Thinker:

• Prefers indirect approach, caution, analysis, organization, precision, problem-solving, and solitude.
• Avoids openness, group activities, and spontaneity.
• Does not easily display or  acknowledge emotions.

While Directors and Socializers are fast paced, the Directors are focused and Socializers are easily distracted in nature.

Directors and Thinkers both like to keep a distance from others; however, their reasons are different. Directors prefer control, and exercise this control in disclosing their personal information. Thinkers, on the other hand, put exacting standards on themselves and are afraid to display themselves in poor light.

Socializers and Relaters are people-friendly, but Relaters prefer intimate one-to-one setting. Socializers are quite opposite, and get involved with too many people, too many activities, and too much impatient talk.

Thinkers and Relaters both prefer indirect cautious approach and do not easily get into conflict.

You will notice that there are similarities and differences between styles. As you would expect, a number of style combinations emerge from this classification – some are naturally successful and some need deliberate work. If you can understand and classify your SME’s behavior style, it would be easier to plan your communication strategy.

For example, the Director SMEs will initially hate you for encroaching on their time. But since you know that Directors take great pride in delivering results, focus on the results. Explain how you need the information immediately to complete the entire project as scheduled. You will soon find that the required information not only arrives in time, but also contains pointers to future planning.

You need not spend any extra time to “get to know” the Directors. As long as they recognize why you need to interact, the interactions will be short, smooth, and conclusive. Once you establish that both of you have the same final objectives, your personal equation is firmly set. Irrespective of your own behavioral style and any personal conflicts, the Director SME will always continue to respond your queries.

Cut to the Socializers. They will first talk about a dozen personal things and invite you to the canteen. It would be wise to accept the invitation, for the Socializers need to be friends first, much before the professional relationship. Socializers love to network, so be prepared for party invitations, too. However, they are very open and respect others, so it is perfectly alright to decline.

If you are a Socializer yourself, make the best of the situation. You will enjoy the celebrations besides getting the technical information. On the other hand, if you prefer a much closer relationship like a Relater, continue being friends and evade the group events.

Socializers also like to share jokes, anecdotes, personal experiences, professional wisdom – you name it. If you want to enhance your content with additional information, cases, tips and tricks – they are the right persons. Their time-management is not very rigid, so you can approach them anytime and chat as much as you want. But remember, they have a vivid imagination and a tendency to exaggerate. It would be a good idea to cross-check their version of facts with other sources.

If your SME is a Relater, it is a great boon. In the beginning, you will need to spend extra time to open the Relaters up. But once they become close friends, they will really care about you. The only behavioral style to give information without asking, Relaters will actually do a lot for you.

The biggest problem with Relaters however, is that they are not too good comprehending the holistic picture and hence avoid making decisions. This delay and hesitation will certainly affect your deliverables, and also annoy you if your style is Director. If you also happen to be a Relater then there will be no decision – ever!

Logical, analytical, systematic, plus in-depth technical knowledge, Thinker SMEs can totally make your day. They will explain things to you with charts and diagrams. They will give complete details, justify them, and structure them nicely. They will practically write half of your deliverables! Obviously, you will need to simplify and embellish their writing to make it much more interesting.

Like Relaters, Thinkers prefer indirect approach. So do not go barging in to their solitary shells, but knock gently. They tend to value only Thinkers, dismissing Directors as arrogant, or the other two styles as emotional. If you are a Thinker, you two will bond very easily. But if you are not a Thinker, you will have to first start building trust,which incidentally takes a long time for a Thinker.

The actual interaction pattern between you and the SMEs will vary depending on your and their style combinations. However, you can always keep your calm and employ the general communicating strategies as:

• With Director SME, be direct and focus on work.
• With Socializer SME, mingle a lot but be firm about work.
• With Relater SME, show affection and be sincerely concerned about work.
• With Thinker SME be formal and show systematic work.

So is it possible to find your own behavioral style? Check out some free tests on the Net. Try them from the SME perspective, too. Your possible combination will emerge and then onwards, communication with SMEs will be a breeze!

The Platinum Rule® is a registered trademark of Dr. Tony Alessandra. Used with permission. For more information, visit www.Alessandra.com and www.PlatinumRule.com.

About the Author

Dr. Meghashri Dalvi has combined her love of writing with engineering and management experience to create a successful career in technical communication. She currently works as Consulting Technical Communicator and Researcher at Progress Software. You can reach her at meghashri_dalvi@yahoo.com.

No related articles.

I have been attending STC India Annual conferences for the past five long years. I wish to take this opportunity to share a few points/suggestions with you so that you can plan better for this year’s conference:

• This year, the 13th STC India Annual Conference takes place in Chennai from December 1 to 3. Although Chennai experiences the harshest of summers, December and January are the coolest months of the year. Temperatures fall substantially down to as low as 20º C at the peak of winter.
• Advise you to stay in a hotel which is closer to the conference venue. In this age of internet, travellers offer feedback on the hotels and rate them accordingly. It may help you to decide to stay at that hotel or not. Remember that you have a networking dinner to attend on the main conference day that usually goes on past 9 PM in the evening.
• Book your tickets (air/railway/bus) in advance. I know that most of the times the delegates have to wait till the last minute before registering for the conference. But, if you are sure that you will attend the conference even if your company does not sponsor your trip, it makes sense to book your tickets a bit early.
• Arrive at the conference a bit early. It is understood that most of the delegates attend the conference and skip the pre-conference workshops. But, then arriving at the conference location a night earlier would help you. Many a time, there are requests for a conference slot change. It is better to address them earlier to the program management team.
• Scheduling to attend the sessions: Most of the STC India Annual Conference offer parallel sessions. This is done to accommodate as many conference topics as possible and offer delegates the choice to pick and choose sessions. If you are traveling in a group, do decide amongst yourselves who would attend which sessions. A KT can be done later by your friends on the sessions you have missed. In this way, you can make the most of all the sesisons.
• Read the conference newsletter carefully. It usually contains key information which can be useful to you. Also, the agenda contains abstracts of the papers being presented by the speakers. It will help you decide whose sessions you would like to attend.
• Never miss the opportunity of networking. You may wish to go to a sponsor stall booth and look at their offerings. You may get a chance to drop in your resumes if you wish to.
• Do not forget to keep the boarding passes, hotel bills, cab receipts and so on of the conference. You may require this for your reimbursement later.
• Keep a diary/notepad and record the summary of each session that you attend.

We recently concluded the 1st STC India UX Conference. 80 people attended this conference that was conducted at Welingkar Education College, Bangalore, and it was a terrific experience.

I look forward to meet you at the 13th STC India Annual Conference.

Possibly related articles:

1. Prez Talk
2. Prez Talk
3. Prez Talk

• SUMMIT@aClick is an online collection of the conference’s content, with audio and PowerPoint synched together. Almost all of the 80-plus presentations at the Sacramento summit were recorded, and SUMMIT@aClick offers them at a nominal price.
• STC’s Notebook celebrated its second birthday on 3 August 2011. Some minor changes were done to the look and feel. Your suggestions are welcome here.
• Upcoming certificate course are listed here. These include DITA from Legacy to the Future, Managing Virtual Teams, Tech Comm Manager, Instructional Design for e-Learning, and TechComm 201. Also check the special offer for TechComm 101/201 certificate courses here. Certificate courses are regularly added, so keep checking the main certificate course page regularly.
• In the 21 July Board of Directors meeting, the Board voted to reduce the number of Directors from six to four, starting with the 2012 election. With this vote, there will be two Directors elected next year rather than four. The details are shared here.
• A new effort from STC—the Alumni Renewal Offer works towards bringing back former members. Announcement post can be read here.
• STC Vice President Alan Houser and The Content Wrangler’s Scott Abel will discuss your options for plugging into social networks and professional societies in the field of technical communication, in this webinar titled ‘The Power of Many: The STC in the Age of Social Media’. It is scheduled for 21 September 2011.

Possibly related articles:

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

1. When you must include specific product names, version numbers, file paths, window names, wizard panes, field-box names etc. that might change during the SDLC, do not hard code them. Use variables.  If writing with DITA, use conrefs; if writing with MS Word, use fields; if writing with any other help authoring tools, use the features that the tool has for handling variable content.



2. When writing a procedure, do not document the workarounds for any step that does not work as designed; do not document bug fixes in procedures.  Write the procedures like they should normally work; write the bug fixes elsewhere (Troubleshooting?) and give a cross-reference in the procedure.  Clean procedures are easier to maintain from release to release; bugs get fixed from release to release and the documented bug fixes can either be updated or retired.
3. If you are going to re-use something, do it from one single location instead of giving in to spaghetti code# and reusing from file A to file B, then to file C, thence to file Q.  If one file in that chain moves elsewhere or ceases to exist, the whole link breaks; besides, it is easier to keep sight of a fixed target than a moving one.

# Spaghetti code is a pejorative term for source code that has a complex and tangled control structure, just like a dish of spaghetti.

About the author:

Anindita Basu is a writer and editor at IBM. She can be reached at anindita_basu@shortmail.com. Illustrations are courtesy www.makebeliefscomix.com.

Possibly related articles:

1. DITA Writing Tips
2. Writing My First DITA-Ready Topic
3. Writing Tips

- Manjusha Nair

In earlier articles in this series, we have planned for our agile project, and we have gathered the requirements. Are you still wondering how we can actually write for agile? If you wonder how we can develop documentation that is release quality and free of errors, in just a couple of weeks, you are not alone. The shortage of time and an absolute lack of specifications documents worry most technical writers who are new to agile.

Let’s look at how we can overcome these obstacles and create effective documentation during a sprint.

Participate in sprint planning

Every sprint begins with a sprint planning meeting. You must be a part of this meeting and sit through the whole meeting till a plan is drawn. Why I say this is, you may feel a little left out and may not always understand technical discussions, but it is extremely important that you attend this meeting.
When you hear the developers discuss each item in the backlog that they are planning to take up in the sprint, you get a good idea of what you’ll be dealing with in the sprint. It also allows you to form a mental picture of the final product you’ll be documenting and gives you the confidence to be able to come up with estimates and timelines for documentation. Similarly, when you share your inputs, the development team appreciates what documentation teams do and this shared understanding of work goes a long way.

The to do list

Refer to the high level plan you created. This keeps you on track and guides you in achieving the desired results. Draw up a personal sprint plan just for documentation, it will keep you sane and on track through the sprint. This plan need not be elaborate – it could just be a list of the tasks you need to carry out in the current sprint with the times that you set yourself for these tasks. Also, jotting down what you need to do gets you prepared to ask the right questions and not appear clueless in the early stand up meetings.

Involve the team

You cannot work as an island in an agile project. Involve the team early on by taking real interest in what the others are doing, and showing them how documentation is important to the project. You can discuss the following points with your team:

• Will they be creating any design documents at all? If yes, by what time?
• How quickly can they share a prototype / wireframes?
• Are there any other tasks you can help with? (This depends on how much time you have.)

Use the user story

After you have read the user story and interviewed the developers, you have a high level understanding of the feature and where it fits with the other features. Now you can start writing the draft. This draft will surely go through a lot of changes before it can metamorphose into the final document that your end user would see.
The best documentation method that works for agile is task oriented writing. When writing, start from the user story as a base, which being task oriented by itself, will guide you in developing task oriented documentation.

Less is more

Agile is a very good way to avoid unnecessary fluff and concentrate on only what is needed. Documentation for agile projects needs to be to the point and concise. There is simply no time to include ‘just in case’ or unnecessary information. This means that you are not simply including information because ‘it is there’. You actually look at what works best for the tasks at hand.

Here are some tips for writing to the point:

• If something can be said in 10 pages, don’t write 20. If something can be said in 5, don’t write 10.
• Write in bullet points or steps. This cuts out the fluff.
• Write just enough background information to provide a context.
• Start with a skeletal document that covers the minimum information that users need to perform the tasks on hand, and then augment it as required.
• Keep diagrams and illustrations simple.
• Do not repeat any information contained in any other document – simply create a reference to it.
• Focus on the needs of the end user of the document. Do not pack in everything the developers think the documentation should include.
• Every document and every topic within the document should serve to fulfill a goal. Question each topic and each sentence, ‘what purpose does this serve?’ and only if you find an acceptable answer should you retain it.

Test the documentation

Remember to get the QA team to test the documentation alongside the software/product. This is a sure way to weed out errors and check if the help really helps. This can easily be done as you are writing the documentation at the same time that the development team is developing the application. There is very little lag, if any. Also, the documentation is concise and task based which makes is easy of the testers to test alongside the software.

Some things that may derail documentation, if not planned for:

• The engineering team may create small specifications documents for their reference, which might become available to you sometime during the sprint. You can use these to check for errors and strengthen your draft. But if not planned for, you will find it difficult to include new information at that point.
• You will probably get the first look of the UI towards the middle of the sprint. Considering that you have already been working on the draft, this obviously requires you to make changes to the documentation.
• The testing team’s inputs, which typically come towards the end, might also lead to changes in functionality.
• Technical teams sometimes take the ‘known defect’ route to beat time. In other words, they may ask you to include a few notes or caveats, because there is no time to fix the issues in the build.

You are working agile, which gives you a lot of freedom to explore new possible areas of work. You can help with labeling and micro-text, of course. But you may also find that you can help with testing, or if you are tech-savvy, coding as well. Agile does not define goals for anyone in the team, which means any of you can pick up any of the tasks on hand.

In an agile environment, you work as a part of the team and not in a doc-silo like most waterfall projects. If you keep up the pace and the quality, you can reap rich rewards: on-time, succinct, task based documentation is, of course, the tangible benefit; but apart from that, you also get to bond with the engineering team and form functional networks, which go a long way in helping you gain domain expertise and confidence.

About the Author

Manjusha Nair is a content specialist working with Infosys, Bangalore. She is passionate about innovation and sharing knowledge. In her spare time, Manjusha likes to write poetry and fiction.

Possibly related articles:

1. Planning for AGILE
2. Requirements Gathering for Agile
3. RCO, Estimation, & Ratio Analysis Technical Documentation, Part 3

Possibly related articles:

1. July-August 2010 Newsletter
2. September – October 2011 Newsletter
3. May – June 2011 Newsletter

- Devarati Banerjee

A sip of wine, a filling lunch, and a smoke-filled rendezvous over editing and publishing a book, has now long become a part of book publishing’s glitzy past. In those days, when technical writing was just changing the face of the IT industry, editing was still ruling the book publishing world. And the layout for most of these book editing packages would be similar – the editors would be mooning over every word to its last syllable, and editing with full gusto. But now the question arises that with the zeitgeist of the IT era setting in, and technical writing selling out new profiles, has editing in the technical writing world become a little wobbly in its intensity than in those earlier ‘book publishing’ days? Has the rigorous word-by-word editing process paled in recent years? And is it merely a casualty of the demands of meeting strict deadlines and catering to customers’ wishes of delivering the edited documents at the end of day?

Reach for the latest document that you have edited recently, and you might find yourself piling up the mistakes you missed last time. Could you find out the true reason for missing all those errors during the previous edit? Could the answer lie in the changing role of an editor, in the turning wheel of the IT industry and expectations of our esoteric corporate clients? I firmly believe that editing a piece of work is a balancing act between understanding the context of the topic and sentiment of your target audience, grammar and words, client requirements and understanding products and services. When we set forth on an editing job, the first question that arises is – where do we begin? This article discusses some questions we can ask ourselves or guidelines we can follow.

Abridging just for the sake of abridging does not constitute editing. Neither does it constitute replacement of words with synonyms. I am personally opposed to abridging unless when absolutely necessary.  At times the job of an editor is tricky, because English can be tricky. Know the difference between words that sound similar, for instance accept/except, effective/efficient, exceedingly/excessively, further/farther, hyper-/hypo-, insure/ensure and so on.

Also, know the differences of which vs. that, who vs. whom, compared to vs. compared with, speak to vs. speak with, et al. Yes, grammar is open to interpretation, but these mistakes result in a Manichaean choice between right or wrong.  Most often, people wouldn’t take the trouble to analyze the subtle differences that underline these words. And they would be left tossing a coin to decide on the usage or simply overlook some aspects. When faced with such a dilemma, resort to the next best thing to knowing, judicious tools like the Oxford/Cambridge English lexicons, may be even Word Web, to write the right way.

Just the other day, I was perusing an article on a novel, Freedom, by Jonathan Franzen. It transpired that on the evening of his book release, Franzen discovered that a series of errors existed in the UK edition of his novels. But a million copies of the novel were already enroute to the renowned bookstores. A highly shaken but phlegmatic Franzen, apologized to his audiences and asked them to refrain from buying the books. To pile up on ironies, the article concluded that one section of Freedom is presently dedicated to the heading “Mistakes were Made”.

Authors are meant to write. But what should an editor do? The editor brings in clarity and consistency to thoughts and ensures coherency in the flow of content. Clarity does not involve changing every word. For example, the sentence “There is much data available on the ills of using plastic, but not many people take it seriously”. If given a chance to edit, there’s a redundant word ‘people’ in this sentence, which is screaming to be removed. It’s almost similar to a statement – “The sky is grey in color”. Such extracts solve no useful purpose apart from suggesting that a novice is at work.

Also, checking your spellings entails a good job by an editor. Ensure clarity between its/it’s, their/there, and with words ending with –able/-ible, -ae/-oe, -ative/-ive, -ce/-se, -ant/-ent, -cede/-ceed, -efy/-ify, -ei/-ie/y, -for/-fore, -or/-er, -in/-un, -ize/-ise, and -ified/-yfied. Use spell check to catch errors, but do acknowledge the limits of an electronic spell checker.

Mastery of editing also rests in enlivening your verbs, taking the steam out of transitive and intransitive verbs, and understanding the differences of countable and uncountable nouns. Look out for different forms of ‘be’ verb such as am, were, is, been etc. This sleepy ‘be’ verb along with words like ‘done’ suggest inactivity. For example, “A review of the documents was done by the editors”, can be rephrased “The editors reviewed the documents”. Also, note the subtle nuances of ending with transitive and intransitive verbs, and understand how countable nouns such as book, fruit, etc. can form plurals, while uncountable verbs such as feedback, experience etc. remain decidedly single.

Finally, to scale great heights in the editing profession, one must invest heavily in reading. Many of the greatest editors, who own a ‘feel’ for grammar, have developed their special skill through extensive reading. Read for knowledge, and to notice the writing style, read to distinguish words and their particular usage, and to catch on with prepositions and wake your verbs, read to learn how to eliminate a redundant conjunction or dodge a verbose construction, to stop the modifiers from dangling in mid-air, and ease out clichés, to place correct antecedents for pronouns, or grab the typographical slips, the stylistic infelicities, and the freak glitches that often clog a piece of writing.

Perfection in writing is impossible, but editing is taking a whole new dimension in the form of a new generation of young and brilliant editors, who at the end of the day, would not only clean up the rough edges, but also elevate the experience of reading to a new level that would tease the minds and touch the hearts of readers.

About the author:

Devarati Banerjee is a member of the Technical Communication (TechCom) team in Tata Consultancy Services (TCS). With over six years of experience, she is highly passionate about reading, writing and editing.

No related articles.

In this edition of Experts Ignite, we bring you perspectives on Content Management Systems (CMS) and process management in the implementation of CMSs and CMS tools from a seasoned professional, Ralf Wittgen. Ralf Wittgen is the Director, Operations, at Author-it Software Corporation in Auckland, New Zealand. He is responsible for all client facing activities, from consulting and training in implementation projects to client support and assistance.

Ralf started to work with Content Management Systems when the term itself was not yet “invented” by the industry. In 1996 Ralf designed and implemented a repository for technical authors to find content in a database. Just years later, Ralf was involved in leading edge projects such as publishing an interactive spare parts catalogue in HTML from SGML. In the last few years Ralf has focused on process management – certainly a hot topic in Technical Documentation. “A process runs through the entire business”, we hear Ralf often say. “So for being successful on our projects, it is essential to understand the connection between business requirements and processes.” Let’s hear more from him in person.

Tell us about your start in the content management industry and with content management systems.

I actually never arrived in the content management industry, it is more that I was in this industry from the very beginning. One of my first projects after my university time was to design and implement a repository for technical authors to find information saved on a desktop computer. Today, this feels like the “stone age of CMS” – literally this was a very early form of Content Management, with indexing techniques, hyperlink concepts and very smart retrieval functions based on “tagging” documents with meta data. Years later we published one of the first electronic catalogues for an Internet Browser – based on authoring in SGML and publishing straight to HTML. XML existed at those days maybe only in the head of some folks (may be some of our readers recall this time). Since then we have seen a rapid and exciting evolution of the concepts of CMS, and I never left our industry, it’s just too exciting.

What is the role of process management for the successful implementation of a CMS?

Maybe 10 years ago, you could simply install an application on your local machine and create technical documentation, you were designer, administrator and publisher in the same role. Today we have to implement a CMS environment with users spread all over the world. With users taking different roles like translation coordinator, authors, designers or reviewers. Any documentation, regardless if is a technical manual or a training guide, is created within this environment and is part of a “bigger” manufacturing process: The technical documentation is often a legally required part of the product delivery.

Try now to draw a picture and you will soon understand how important process design is when implementing a CMS. In our project clients are often driven by “functions”, especially at the beginning of a project. They express “I need a check-in/check-out function”. We are convinced, that this is a misleading statement – in this particular example you should more consider “If user A has opened a document, other users can open it only in the read-only mode”.
I recommend that you start first with your business requirements. Focus on aspects which are measurable – such as “Reduce translation costs by xyz” or “Reduce translation time by xyz”. Then continue with the design of the (documentation) process – today we’re all talking about the collaborative environment. Ensure, that each process step create value towards the business requirements. Create use cases or user scenarios as a foundation for this design. You will very soon realize that your functional requirement “check-in/check-out” does not really contribute to your measurable outcome.

You have been managing a team spread across geographies in Author-it Corporation. What according to you are the constraints or difficulties?

The biggest challenge we’re facing are the time zone differences: Just imagine to organize a project meeting, with a client from somewhere in Asia, a consultant from the US and the project manager from New Zealand. We even had projects in which we had to include consultants from Europe! Web meetings such as GoToMeeting are great tools to bring teams together. And don’t underestimate the importance of seeing your project partner in this “virtual world”, it makes a huge difference – we’re all human beings and need this “visible” interaction.

A further very important aspect is that we use within our company a standardized approach to implement projects. Although, we have always different client requirements in each project, we follow an internal Best Practice guideline when going through project phases such as “Discovery & Analysis”, “Training”, “Importing Legacy Content” or “Roll-out”. It allows us to “synchronize” all project team members among the different time zones.

Another challenge is to collect and propagate experience we made in our projects for the entire Global Services team. Just recently we have started to design and create a Global Services Knowledge Base (straight from our AIT library!), which will help all our consultants to search for specific topics, results, problems etc. we had to solve in our projects.

Can you share any interesting projects in a CMS implementation that you have worked on recently?

Very often we have the big implementations in mind. But look, we shouldn’t forget that smaller implementations can often benefit from the experiences from bigger implementations. A few months ago we could complete a small project for a client in the US. It was just for three authors with the main request to publish to PDF in different languages. We designed together with the client the documentation process, then implemented together with the client Author-it. With “together” I mean that we follow instead of a simple “training program” a “hands-on concept” which literally means, that we do several onsite workshops with the client. Ultimately with the goal, that our client can make any future adjustments (configurations) on their own. The end result: A great reuse management concept which allows the three users to produce “more output” than before in the same timeframe, despite multiple custom products. It reduced the costs for translation and allows now a faster production of the final documents.

What is your vision of technical communication in the next five years?

There is a very exciting road ahead of us. I am convinced that we will see a “virtualization of our documentation projects” – content contributors and content reviewers are no longer in the same office (or time zone). Print will play only a minimal role and online publication will become a success factor and a differentiator when you compare yourself to your competitors. Authors are no longer bothered with anything like tags or xml, creating the (reusable) content is in the middle of the focus. Links are created automatically based on the content, not on manually created hyperlinks. Publishing changes, maybe instead of creating an online help we publish content to an intelligent wizard providing information to your end users depending on the end user’s current situation and information request. And we hopefully need no longer to publish to paper.

Compiled by an STC India volunteer.

Possibly related articles:

1. Experts Ignite
2. Experts Ignite
3. Experts Ignite

- Harry Anthony

A Manager or an individual needs to be effective with making decisions ranging from large to small on a daily basis. Managers/individuals must be problem-solvers and who can make decisions instantly.

It is critical to first prioritize problems based on issues that effect on the organization. Those that stand to have the greatest impact should be dealt first, and all problems need to be addressed in a systematic way prior to a decision being made.

Because a first impression cannot reflect the entire situation, an individual must avoid jumping to conclusions. Collecting information from more than one source to avoid bias, and completely assessing all pertinent and verifiable information prior to rendering a decision is strongly recommended.

Collecting information in order to obtain a complete understanding of the issue is only the first step. Once the information is available, then it is wise to brainstorm different solutions and possible alternatives in order to get more than one perspective. Such options can start out as wide-ranging, and then can be narrowed down to fit the scope of the problem.

Having identified a set of options and solutions, feedback and suggestions on them, along with alternatives, should be sought from consultations with others. For the most part, group decisions particularly where the group contains people who the end decision will affect  are preferable to those made by individuals as a pool of knowledge, skills and experience can be drawn upon.

Then comes the time to weigh the pros and cons of a decision. Which option or solution gives most to the organization whilst taking least from it? Few decisions will be as clear cut to hold no drawbacks. Negatives are acceptable though, as long as the positives sufficiently outweigh them.

Decision Making Requirements

To make effective and efficient decisions:

• Consider and consult for opinions with each individual involved in the team.
• Sometimes we need to listen to our intuitions to make possible decisions but make sure it aligns with the project goal. It’s important to discuss what your intuition thinks with the team before making the decision.
• Make decisions based on the group discussions and processes established by the organization. It must address the following requirements:
  • To establish the context and decide how we need to work as a team requires:
    • Right people (Key stakeholders, experts, and opponents)
    • Right place (Conference rooms, off-site locations, and face-to-face discussions)
    • Right process or approach (Team consensus, Majority wins, Qualified consensus, and Directive leadership)

Note: Be open to other alternatives to make decisions but don’t make or take decisions alone. Create a consistent climate

Important! Sometime even the good Leaders can make Bad decisions.

Do’s

• Try to find out symptoms and root causes for the problem not just the symptoms.
• Perform a root cause analysis to know why the problem is raised.
• Question yourself and team to know what exactly the problem is and find the root causes for it.
• Encourage a productive dialogues by:
  • Open  team discussions
  • Think out of the box using all of the available information
  • Assign tasks and deadlines
  • Recognize and thank team members who are involved in making a positive decision
• Promote a fair process to acknowledge and consider ideas by the team members.
• Identify the alternatives and evaluate them.
• Pay attention to what’s different.
• Make complex decisions with partial information. It is difficult though.
• Resolve disagreements and move towards making final decision by:
  • Revisiting and retesting assumptions
  • Verifying that the objectives appropriate
  • Setting a deadline in advance
  • Agreeing upfront on the disagreements that cannot be resolved
• Communicate and implement the team’s decision by notifying the stakeholders involved and people affected by it.

Note: An individual cannot make decisions independently when he/she works in a team that follows a process-oriented approach.

• After communicating the decision identify tasks, assign resources, and set deadlines to accomplish your decision.
• Give room for tweaking the final decisions with some adjustments.
• Increase your odds to be successful in implementing your decision.
• Make ethical decisions and question them when required, by:
  • Legal test
  • Stakeholder test
• Follow these steps to identify your decision:
  • Specify  all objectives
  • Define successful performance level and outcome
  • Paint a picture of what things will look when problem is resolved
  • Make sure objectives and outcomes are not conflicting
• Follow a prioritization matrix to make a well calculated decision.
• Follow the point-counterpoint technique.
• Follow the virtuous teaching cycle. (i.e. Learn &Teach and Teach & Learn).
• To lead the team towards the best decision have the following:
  • Ideas
  • Values
  • Emotional Energy
  • Judgment Calls (Yes or No)
• Lead with questions.

His newest book, “Know What You Don’t Know”, helps business leaders find and prevent problems before they happen. In his previous book, “Why Great Leaders Don’t Take Yes for an Answer: Managing for Conflict and Consensus,” Professor Roberto shows how to manage the interpersonal dimensions of decision making — the social, political, and emotional aspects that so often determine success.
He is the Trustee Professor of Management at Bryant University. Professor Roberto served for six years on the faculty at Harvard Business School and has been a Visiting Associate Professor of Management at New York University’s Stern School of Business.

Don’ts

• Don’t base your decisions on your past success
• Don’t be over confident of your assumptions and develop few alternatives
• Don’t resist major deviations
• Don’t be biased on your opinions and ignore the facts that might provide other alternatives
• Don’t follow the extreme individualism behaviors, it will lengthen the decision making process and interfere in making right decisions
• Don’t assume at the very beginning itself that you know what the problem is
• Don’t use faulty analogies
• Don’t make decisions too early or too late.
• Don’t communicate the incomplete information to the stakeholders involved and people affected by the decision.
• Don’t just be a learner but try to become a teacher of what you learnt by sharing the knowledge that you gained.

About the Author

Harry Anthony is a senior technical writer with ten years of experience. He has written documents for variety of audiences, with emphasis on product manuals, user guides, white papers, web content, online help, recorded web classes, live virtual class, and installation guides.

He holds a bachelors degree in the commerce and postgraduate diploma in computer applications. He is pursuing his Masters in Business Administration (MBA).

Possibly related articles:

1. Applying Business Process Principles to Information Design

By Larry Kunz

We are part of a profession that is undergoing rapid change. Several trends, spurred on by advances in technology and by the world economy, affect us. We need to understand what these trends mean to us as professionals, and we need to recognize how we can influence these trends.

The first decade of the 21st century saw major changes in the technical communication profession. Content is increasingly being designed for single-sourcing and reuse. Audiences look for information in other places besides the user manual and the company website. Practitioners struggle to demonstrate their value as the job market tightens.

The next ten years will be just as eventful. These trends are continuing, and new ones are emerging as well. Here are the major trends that I think will affect technical communicators in the 2010s:

• Community-based content, and with it the rise of content strategy and content curation
• More media and more devices, like smartphones and other personal devices
• Continued commoditization of technical writing—and, in response, an emphasis on proving that there is real value in what we do

Community-based content—and the need to manage it

Traditional technical writing has been a one-way communication channel: a company or organization publishing content for its readers. Recent technology, however, has established a two-way channel in which the “crowd” or “community” contributes content as well.

With community-based or user-generated content, traditional documentation is augmented by things like blogs, forum posts, and user comments. With so much content coming from so many different sources, there’s clearly an increasing need to manage it. It’ll take a lot of work, and a lot of issues need to be resolved. Who decides what content is suitable to publish? Who decides what content should receive emphasis? Who edits the content to ensure that it conforms to standards for editorial quality, corporate branding, copyright protection, and so forth?

The term content curation has been coined to describe these tasks, and the people who do these tasks are content curators. But what are the qualifications for becoming a content curator? And under what guidelines is the work of content curation performed?

Many observers agree that the task of content curation can’t be done properly unless there’s a content strategy to codify policies and procedures for analyzing, collecting, managing, and publishing the organization’s content. (I’m indebted to Rahel Bailie, http://www.google.com/profiles/rahel.bailie, for this succinct definition of content strategy.)

The star performers of the 2010s will be content strategists (the people in charge of developing and enforcing the content strategy) and content curators who can meet audiences’ demand for information that’s tailored to them and to the tasks they perform. This is good news for us because the skill sets required to fill these new roles are very close to the skills we already have as technical communicators. For example, we know how to do audience analysis, we know how to organize content, and we know how to develop content that conforms to a corporate style guide.

More media and more devices

Ten years ago, how many of us had heard of iPhones or Blu-ray—or even podcasts? The 2010s will bring just as much innovation, with people consuming our information in ways we can’t imagine today. We have to be ready.

Here’s just one example. I’ve seen remarkable prototypes involving animated graphics—guiding an auto mechanic, for example, through the steps involved in repairing an engine. Seeing those prototypes has alerted me to the fact that I should hone my skill at creating graphics. I’ll also need to learn how to make my graphics portable enough to display on a whole universe of devices, many of which have yet to be invented.

There’s another twist to this trend. How can publishers, including technical communicators, pick the media that will be viable in the long term without being led astray by fads? The proliferation of gadgets seems like it’ll never stop. There’ll be winners and losers, though, because there always are. In addition to expanding our communication skills, we’ll need to become adept at guessing which new technologies are worth our time and effort, and which ones are not.

The need to prove the value of technical writing

Increasingly, companies in traditional markets like the U.S. are finding that they can get good writing from abroad for a fraction of what it costs at home. This trend is accelerating as workers in emerging markets like India improve their writing skills. To remain viable, writers in traditional markets are forced to reinvent themselves—perhaps as content curators or content strategists.

On the surface, this would seem to be good news for technical writers in India. For the next several years, in fact, I foresee a healthy growth in the number of jobs and in the salaries for technical writers in India. According to STC India’s 2010 salary survey, median salaries in India are about 28% of U.S. salaries, up from 12% in 2002. This growth will taper off eventually, however. As Indian salaries get closer to salaries paid in Europe and the U.S., companies will have less financial incentive to engage Indian technical writers.

When will the growth begin to taper off? It could happen as soon as 5 to 10 years from now. At that time, it’s likely that Indian technical writers will face the same situation that their U.S. counterparts face today: the need to reinvent themselves in order to remain viable.

As technical communicators vie to prove their value, they’re increasingly looking for ways to differentiate themselves in the job market. After years of study, STC recently introduced a certification program. The program will succeed if two things happen: first, a sufficient number of practitioners must choose to seek certification; second, employers must acknowledge the value of employees and applicants who hold certifications.

In addition to the STC certification we might also see a course curriculum, similar to the PMP curriculum developed by the Project Management Institute, for content strategists or information architects. Almost certainly, we’ll see more tool- or process-specific credentials.

Finally, as technical writers seek to retain their value in the job market, we’ll naturally see an emphasis on persuading our employers that what we do—the practice of technical communication—has significant value. It won’t be enough, however, to show that technical communication has intrinsic or intangible value. We must demonstrate value that can be measured on the company’s profit-and-loss statement.

If we do this right, businesses will see that they need good technical communication to help them succeed in the marketplace and avoid the costs associated with product liability issues. It’s up to us, the professionals, to hone these messages and make sure that they’re well understood in corporate boardrooms.

Working toward success

Our profession is changing, and we would be foolish to ignore the trends that are bringing these changes. Yet we cannot regard the trends simply as a wave that will wash over us as we observe passively. The way we respond to the trends will determine whether we as individuals, and whether the profession as a whole, can thrive in the next 10 to 20 years.

About the Author

Larry Kunz is a project manager and information architect with Systems Documentation, Inc. (SDI) Global Solutions in Durham, NC, USA. In more than 30 years as a writer, manager, and planner he has experienced the transition from book-based documentation to today’s integrated delivery of information from a wide range of sources using different formats and media.

Larry has managed and provided content for both technical writing projects and marketing projects. He holds a Masters Certificate in Project Management from the George Washington University and teaches a Managing the Information Development Process course in the Technical Communication certification program at Duke University. He is a Fellow in the Society for Technical Communication (STC) and in 2010 received the STC President’s Award for leading the Society’s strategic planning effort.

Larry has presented at many STC Summit conferences and other events, including the first STC India Summit held in May 2011.

Possibly related articles:

1. Technical Communicators as Heuristics Reviewers

In this edition of Experts Ignite, we bring you perspectives on technical writing management, innovation, and growth from a seasoned professional Sairaj Vaithilingam. Sairaj leads the Content and Design Services (C&DS) practice at Cognizant. C&DS comprises three units: User Experience and Design, Technical Writing, and eLearning. C&DS has over 1200 associates, and is perhaps the largest such unit among peer organizations in India. Sairaj started his career in the software industry as a Technical Writer. In Cognizant, he established the Technical Writing group and subsequently expanded into the other service lines. Sairaj’s goal is to make his team in Cognizant a global leader in User Experience and User Adoption services.

How can technical writers bring in innovation and practice continuos innovation?

There are several factors that contribute to innovation. The first is the individual’s characteristic. You need to have a constant questioning mind. You need to have the mindset of looking at what you do and looking at what is happening around you, and seeing how you can make things better. Having this characteristic alone is not enough. You need to have the courage to speak up, take charge, and make things better. I’ve noticed that such people grow quicker in their career and make great leaders. The next, but equally important factor, is the office environment. The organization and leaders need to create an environment that encourages innovation and recognizes people who come up with ideas. Any individual’s spirit will be killed if he or she is constantly suppressed from innovative thinking.

How does the Content and Design Services (C&DS) team of Cognizant ensure a seamless balance between creativity and technology?

We try to provide an environment that encourages creativity and innovation. We ask our associates to constantly see how they can do things better. Technical Writing, or more specifically User Documentation, need not be a standard type of deliverable project after project. Technical Writers need to think deeply on what is required and see how best they can present content for efficient usage. With this approach, we become consultative and guide clients on what is best for the users. However, much of this is in the characteristics of individual technical writers. You can either choose to think and deliver what is best for users, or you can follow a given path.

In a large team, how do you measure the productivity of each writer? How do you map the productivity metrics to the specific business unit revenues?

Cognizant has systems that help us capture several metrics including productivity. Productivity is measured through the entire documentation cycle. For example, a project is estimated and planned based on benchmark effort figures. When work is distributed to a team, the timelines are drawn based on the planned effort. The actual effort is then tracked. There could be productivity variations among team members and this is valuable information for managers to plan training or even to understand the capabilities of individuals. Periodically, the estimation factors are updated with new benchmark productivity numbers. Productivity metrics have a definite impact on program and business unit revenues. There are benchmark numbers on revenue per employee and total headcount required to achieve a revenue target, and as business leaders we constantly strive to improve practices to better these numbers.

What are the different domains a technical writer gets to explore in your team? Also, what are the various growth opportunities for writers?

Technical Writers in Cognizant are exposed to quite a variety of domains and work. First, there is a range of industry domains like Banking, Insurance, Retail, Healthcare, etc. The thrill of technical writing is in working across these industry domains and learning so much about these businesses. Then, there is a variety of documentation types too, from User Documentation, Business Process Documentation, Quality Documentation, SDLC Documentation, etc. My team is also foraying into web content, tutorials, user assistance, user-generated content frameworks, and so much more. We look at career growth in three tracks: Technical, where a writer can choose to be a technical writer right through and mature to be consultants in the field; Project Management, where a writer can lead projects/programs; Business, where a writer can become a business leader with P&L responsibilities.

What are the main skills you look at when you recruit a technical writer and a documentation lead for your team?

The core skill we look for in a Technical Writer is strong English Language capability. Writers are writers, and should be able to write well with no language issues. The next is aptitude and the ability to understand technology. Technical Writers should have the aptitude to understand any subject and write clearly about them. A documentation lead should be a strong people-person with strong technical writing capabilities. The first aspect is required to be an effective leader and to create a motivated and high-energy team. The second aspect is required for the lead to know the business and to be an effective mentor to the team.

How has the Indian technical writing industry evolved in the last 5 years? Where do you see a technical writer’s role evolve in the next few years?

I’m not sure if I’m deeply aware of what’s happening in the Indian technical writing industry. Let me give my perception. Around 10 years back, technical writers were engaged in creating documentation for the development work happening in companies. We were largely seen as an internal support team. In the last five years, Indian software firms have been getting higher value work. Product companies too have been leveraging India better for research and development. In this context, the scope and need for technical writing has increased. From functioning as a “siloed” local unit, more technical writing teams are part of a global unit with collaboration across countries. The need for quality and the supervision of global clients of our work has significantly increased. The next few years can only get more challenging for technical writers in India. More companies would be exploring outsourcing of technical writing to India. They need to be convinced about our capabilities and quality for us to succeed in this space. For technical writing teams, there is an opportunity to step out of the shadows of the development team and take on independent technical writing work.

Do you see opportunities for technical writers to move towards user experience and eLearning areas?

Technical Writing is an interesting field by itself. However, a technical writer can choose to move into allied areas like Interaction Design and eLearning with a bit of training. A good technical writer’s information architecture and content organization skills can easily be extended into Interaction Design. The technical writer must undergo training in Interaction Design though. In eLearning, a technical writer can consider the area of Instructional Design. Here again, the technical writer needs to be trained in the theories of Instructional Design to be successful.

Could you share any interesting experiences as a technical writer and as a documentation manager?

Sometimes we have team members who overrate their skills. As a documentation manager, I had to give feedback to a team member and suggested that she goes through refresher training on the fundamentals of English. The associate was shocked as she was an MA in English and argued strongly. I then had to pick out her document and edit it right before her. I explained every error she made. Thankfully, the team member saw the weakness and worked hard to overcome it.

As a technical writer, I was in a project in the US. The client was very skeptical about my skills. When I made my first deliverable, the client called me to his cabin and said that he was very surprised about the quality of my writing. He was not sure if a person from India could write to their expected styles. This made me realize that we face the challenge of overcoming the perceptions of native speakers of English. Their concerns are justified. We need to prove time after time that we can deliver to their expectations. It is therefore all the more important that we are good at the job.

Compiled by an STC India volunteer

Possibly related articles:

1. Experts Ignite
2. Experts Ignite
3. Experts Ignite – Paul Trotter, Author-it

By Lori Sanders

I’ve been a Technical Writer for 12 years, and I’ve spent about half that time overall as a contractor/consultant.  While contracting lacks the job stability, security, and benefits that permanent employment can offer, there are many reasons why being a contractor is desirable for at least part of a technical writer’s career.

The biggest advantage by far that I have experienced as a contractor is getting to work on a variety of projects. This means you learn and practice in a wider variety of tools, industries, and skills. Within one year, you might write XML-based help for a web application used by insurance underwriters, develop eLearning scripts and videos for users of 3D mapping software, and write tips and tricks for a consumer content publishing tool. Very quickly, you get to add more skills and tools to your resume than you would when staying at the same job for a given time.

Working on a variety of projects over a shorter period of time also keeps things interesting and challenging. While technical writing can be fun, and sometimes we get to work on cool and innovative projects, it can also be pretty dull. We often find ourselves doing tasks that can’t exactly be called “writing”, such as copying and pasting XML IDs, running search-and-replace for obsolete terminology, and repetitively capturing sequences of screen shots. Even when we are writing, sometimes it is painstakingly obvious instructions such as “Click ‘Next’ to go to the next page.” If you do these kinds of mundane tasks day after day for the same product, you’re not learning anything new, you’re not gaining new skills, and you’re pretty much bored out of your mind. But as a contractor, who moves from one project to the next, you might still do these same repetitive kinds of tasks but at least it’s on different products, using a variety of authoring tools, and working with new people each time. This actually makes the dull parts of our job a lot more bearable and worthwhile.

While the security of long-term employment is nice, there is something to be said for getting paid for every hour that you work. Contractors generally bill hourly for their work, so you get paid more for doing more work and putting in more hours. This can make the work much more motivating. As a contractor, you are often hungry for work. You have to continually work just to get the work, depending on how much work is out there and how big and good your network is. Once you get a job, you really don’t care so much about things that might bother you at a permanent job, such as desk location or people who are difficult to work with. Somehow, being a contractor frees you from a lot of these concerns because you know it’s temporary and you’re happy just to have the work!

I have also felt more recognized and appreciated, as a consultant, than I ever have as an employee. Often when you step into a project as a consultant, you are a kind of hero or expert (or both!). You might be doing the work that no one in-house wanted to do, had time to do, or knew how to do. Therefore, everyone loves you and is happy you’re there.  And you’re only there for a short time, so people appreciate you more and value your time. Of course this isn’t always the case; sometimes employees resent contractors and won’t give them the time of day when it comes to getting their help.  But if you present yourself as being there to make their lives easier and lighten their load, even those people can be won over.

Perhaps one of the greatest benefits to being a contractor is that you are pretty isolated from company politics. You don’t need to think much about org charts, management changes, project ownership, and such things except to the extent that it affects the people you directly work with, and the contractor budget. Beyond that, you don’t have to worry about it or deal with all the political changes that take place in a company. You are there to do specific work, regardless of drama and change going on around you. This can be very liberating, because it means you are free to just focus on the work.

The major downside of being a contractor, of course, is the instability of the work. You might be lucky enough to get a long-term contract, but then you’re dealing with some of the same issues you would deal with as an employee, and not reap all the benefits of contracting. There are also tax issues with long-term contracting, so some companies use a third entity/compliance agency to hire you as a temporary employee. This can be a good thing for you but again you’re more like an employee without company benefits, in this scenario (though it provides some security and is better than not having work, especially if you like the company). The ideal situation is a market that supports hiring contractors. Sometimes, this can be a market in which companies are laying off employees but hire more contractors because they still need the work to get done. Then again, this kind of market is not necessarily good for contractors because there is a large pool of highly qualified people competing for the same jobs.

Those who are most successful at being a contractor are those with a tenacious, aggressive personality. If you don’t have one, get one. By “aggressive” I don’t mean attacking people in the parking lot. You just need to be willing to work hard just to find the work. Often this hard work does not pay off, and you can’t let this phase you. You have to be determined to find whatever work is out there and get companies to want to hire you. It requires being open minded and willing to keep reaching, and not giving up easily.

Besides determination, your best marketing tool as a contractor is your network. Professional organizations such as STC, usability professional associations, and others related to technical writing are invaluable for building contacts and staying current with tools and developments in the field. But the best kind of “networking” you can possibly do as a contractor is to do outstanding work at every job and make sure it gets noticed by your client, AND (often more importantly) by the other contract technical writers you work with (if you are fortunate enough to work on a team of writers).  Knock the ball out of the park on each and every project you work on, and people will remember you as the one to hire. There truly is no substitute for hard work. Having other contract technical writers see my work has landed me more projects than any kind of marketing or networking I’ve done. In my experience, technical writers are nice people. They’re driven, but not viciously competitive, and are happy to help each other out. The next project they are on, or management position they hold, they will recommend or hire you if they have already seen that you do excellent work. This goes both ways! Keep your eye on other good writers, stay in touch with them, exchange ideas with them, and refer them for work in the future, too.

For those making a transition from employment to contract technical writing, it can come as a bit of a shock that you are often expected to start writing and delivering content almost immediately, for a product that you know nothing about. Normally when you start a permanent job, you might have several weeks to acclimate and learn about the product before anyone really expects you to deliver anything. As a contractor, you have to get up to speed a lot faster than that. The good news is that technical writing lends itself well to this kind of pressure. A lot of people think that you need to be a long-standing expert on a product or technology in order to write about it, and therefore you would need to be working in-house to do this kind of work. Anyone who has been technical writing for a few years knows that this is not true.

Learning new tools and technologies fast is what we DO. You don’t need to work with a product for a year or even a month in order to know enough to effectively communicate what users need to know. The more experience you have, the more this is the case. You just need to be good at learning fast how things work, being in touch with your audience and what they need to know, and being able to communicate that information to them in a way they can understand and organize the information so that they can find it. After several years of experience, you can do this in a week or less. A technical writer friend of mine who has twice as much experience as me once said, half jokingly, “I can write based on rumor.” Meaning – it takes very little for experienced technical writers to get enough information to at least get started on a project and can easily be highly productive very quickly.

The ideal contracting situation is when you start a project and there are resources – human, written, and technical – to help you learn and get started. This usually does not happen, and you roll with it. A more typical scenario is something like this:

You start a project and are expected to work remotely using the client’s laptop, yet your VPN connection is not yet working, or the laptop isn’t ready for you – or both. However, a company email account has already been set up for you. You have been able to retrieve your email and see that you already have work assigned to you, with deadlines, but no way of actually doing the work! In other words, you are expected to hit the ground running and be immediately productive, yet you do not have the tools for doing that! You smile. You don’t sweat it. Having a sense of humor can help a lot here. You can start learning by talking to people, looking over their shoulder while they use the product, and reading hardcopy manuals. If you show a genuine interest in learning, there are almost always people willing to help you.

Being a contract technical writer is more challenging in many ways than being an employee, but it is well worth doing for at least a part of a technical writer’s career.

About the Author

Lori Sanders is a contract technical writer in the San Francisco Bay Area, California. You can reach her at Lori Sanders /  lorimelanie@gmail.com.

Possibly related articles:

1. Effectiveness Workflow for a Technical Writer
2. Story of an Ungadgetted Technical Writer
3. Essential skills for Technical Writers in 2011

By Suchitra Govindarajan

A weekend is a beautiful thing. You may have your hands full with work and family responsibilities, but come Friday evening, you breathe a little easier. You look forward to sleeping in, eating out, catching a movie or just staying put at home. Occasionally though, you might think of spending a weekend more usefully. And what better way to do that than to catch a conference? I really enjoy conferences because they present a great learning opportunity, but without all the stress of work (unless you’re presenting).

I’m happy to say that I spent the weekend of May 7th and 8th this year very usefully indeed. I was at the first-ever STC India Summit held at The Chancery Pavilion in Bangalore. But what is a summit? And how is it different from a conference?

I’d say it is a kind of mini-conference. It was more intimate, more informal (both very good things in my book). There was more emphasis on the content, and less on the rituals associated with a conference. Long and formal introductions, the lighting of the lamp, the keynote address, etc. were all dispensed with. While there is a place for such ceremony, it is also refreshing to see that we can be minimal about these things. Therefore, the STC Summit started with a crisp introduction and, bang, we were in the middle of the first presentation. I think it set the tone for the rest of the event.

As is the convention these days, there were two streams that you could choose from. (At times though, it makes it very hard on the audience to have to choose between two interesting presentations.)

Among the presentations that I chose to attend, a few stood out for me, personally (remember, your mileage may vary).

Planning Your Documentation Project by Larry Kunz: It’s always great when a conference manages to get someone who is well known in the online world. Larry has a very well known blog on the SDI website, so I was looking forward to his presentation. Larry was an articulate and engaging speaker with a comprehensive presentation that took us through the 11 phases of a documentation project. He also spoke about how, in today’s world, the phases are iterative rather than sequential. He talked about the importance of measuring the cost of your project, about having a great documentation plan and about proactively planning for changes.

Decoding Science writing by Manjula Kandula: Manjula’s presentation topic was a breath of fresh air. I’d love to see more sessions like this that deal with related fields (the STC conference in Delhi had one on academic writing). Manjula explained to us the difference between science writing and science journalism, and gave pointers on how to break into science writing. Her talk was peppered with great, topical examples that really demonstrated what an interesting field it could be.

• Document Engineering at Juniper Networks by Hemanth Basrur and Sesi Bhushan Somarouthu: It can be quite a challenge to talk about your company’s documentation process and sustain the audience’s interest, but Hemanth and Sesi Bhushan did a great job of it. Their company, Juniper Networks, seems to have set up quite a robust XML-based documentation system, which solves many of the issues that other companies face. I really liked seeing the demo of the system and hearing about great features like the faceted search.
• Starting a Technical Documentation Services Company by Vinish Garg: Many of us dream of owning our own business but are held back by fear, indecision, or the most common deterrent of all, confusion. Vinish compared the decision-making involved in starting a business with that involved in having a baby. There are emotional, financial and practical matters to consider before you go ahead. I would say Vinish’s presentation was an extremely well-structured presentation, among the best I have seen at a conference. Moreover, all of his advice was extremely practical.
• Performance Appraisals workshop by Kiranmayee: It’s impossible to not pay attention to Kiranmayee. She is full of energy and advice and, to top it all, she had prepared a very interactive session on performance appraisals. She guided us through how we would evaluate our colleagues by getting a few volunteers to perform tasks on stage. She even gave us templates and worksheets to take home. The second part of the session talked about handling the actual appraisal session–for this, I was “volunteered” by Kiranmayee to be one of the participants. I had a great time pretending to be appraised on various fictional criteria by Tharun Unni. I’d say it went better than my usual appraisals!

Among the presentations that I did not attend, I heard that Makarand Pandit’s workshop on freelancing was very interesting and interactive. Mayur Polepalli’s presentation, intriguingly titled “Buddha jumps over the wall”, was also talked about as having been a very well-presented and informative session.

I came away from the conference with heaps of ideas, and not just from what was presented there. I find all conferences, in general, to be quite inspiring. It’s the simple fact of having a couple of days to reflect on your work. I look forward more such events in the future, whether they’re called conferences or summits or something else!

About the Author

Suchitra Govindarajan works part-time with MYOB Australia as a Technical Communications Specialist and freelances in her spare time. When she’s not at work, Suchi reads widely and writes a little. She is also learning to paint, learning to take pictures, and learning to tweet (@suchiswriting).

Possibly related articles:

1. 2010 STC Summit and Member Benefits
2. STC India Conference 2009
3. STC-India Annual Conference, December 2009

By Kris Weylo

When you design, create and deploy websites, the following design considerations can be factored into your web development cycle:

1.1   Technical issues

A simple website created with a few HTML pages and content is usually quite easy to develop and maintain. When more functionality and pages are added, the HTML page format quickly becomes unwieldy to maintain and update, since the pages must be manually updated, and hardcoded scripts must be changed.

Ideally, content must be edited at one point only, even if that content is reused throughout the site. ASP and XML offer some solutions in content management, particularly XML, which allows single sourcing. Many web CMS applications, including open source applications are available, that enable content management. There is a learning curve involved in installing, troubleshooting and using a CMS, which can be factored into your development and maintenance costs.

ASP can be used to dynamically parse pages to the user client. This is very beneficial in larger websites with dynamic content such as syndicated content. To run ASP, Internet Information Services (IIS) must be installed on the server. This can mean that sourcing an IIS enabled host at the outset can be useful if ASP functionality is required later. The more complex the website is, such as if the website uses multiple databases and plenty of scripting, the more technical issues can arise. Many of these problems can be avoided by planning in the pre web development stage. The projected progress path must consider changes in technology, and how the website will adapt when migrating to newer technologies.

Future-proofing a website means, among other things, that the developer should plan for a site that can attain viral growth to something far beyond the original site.

2.1   Web design

If the design is successful, the user interface and site structure complement each other and work in harmony to enhance user experience. However, the less homogenous the audience is, the more the user interface tends to be a compromise. If the site audience consists of both adults and children, the user interface must be a compromise between their preferences.

There is a gap between identifying the audience, and knowing how to satisfy the needs of the audience. There are very few rules on how to customise interfaces for various audiences. Although common sense dictates that a corporate website should look and feel different to the Disneyland website, how should the user interface for a law website differ from an online stock trading website? This is an area where User Experience Design (UXD) can play an important role. This area now receives a lot of attention and there is serious research being done in the field of usability in web design.

The site structure is decided by other factors such as the navigation, and how the pages are linked together. The structure of the site changes as time goes by and the site morphs by cumulative change. Good planning in the design stage allows the structure to grow with the site. These are also issues connected to scalability and improvements in design. A site must be designed for scalability and have the design flexibility to adapt to future changes.

3.1   Website delivery

According to Subtle as a fish, “Currently, over 20% of people on the Internet use one of the many alternatives to Internet Explorer (IE). This figure will only continue to grow as users become more knowledgeable and more comfortable with new technology. Within the IT industry today, over 35% already use an alternative browser.” The major challenge in web delivery today is the cross-browser compatibility and how different browsers interpret and display the same page. The rapidly changing trends in browser usage mean that websites optimised for a browser in current favour can display incorrectly or behave unpredictably when that browser becomes obsolete and is replaced by another. Internet connection speeds are becoming less of an issue due to the rapid penetration of broadband. However, page loading speeds and bandwidth must be considered while designing a page. The faster a page loads, the fewer users click away from the site before the page loads completely.

4.1   Legal, ethical and copyright

Regulations for website accessibility and the Disability Discrimination Act (DDA) are some of the legal factors that can eventually require you to change the content and design of your site to be more disabled-friendly. The Subtle as a fish website http://www.subtleasafish.com/use.html states that “The main aim of the Disability Discrimination Act is to give disabled users equal rights in the area of access to goods, facilities and services.” The act first came into force in the UK in December 1996, with further rights included in additions in October 1999 and October 2004.

The Subtle as a fish website also asserts that the majority of websites online are in breach of the DDA for over 5 years. The UK Disability Rights Commission DRC  investigated over 1000 websites for breach of the DDA. An astounding 80% were shown to fail to provide even the most basic access to disabled users. Although there have not been any prosecutions in the UK, there have been several successful cases in both Australia (which has a similar disability law to the UK) and the USA. There is no specific information currently available to tell companies exactly what their websites need to do to fulfil their commitment to the DDA. However, it is widely believed that the W3C Accessibility Guidelines will be used when a case makes it to court to assess if the website meets the DDA Guidelines.” It is good policy to comply with these W3C guidelines.

Follow the accessibility guidelines set out by the W3C, WAI , and the DDA to ensure your website fulfils its present and future legal requirements. It is a distinct possibility in the future that websites that do not comply with the DDA will be closed down and possibly face financial penalties.

If a website collects and stores information on the users, such as when the users join a mailing list or discussion board by giving some information about themselves, the stored data is protected under the Data Protection Act, 1998. The Data Controller, in this case the Web Developer or Administrator, is bound by the Data Protection Act, 1998. The Data Protection Act requires the Data Controller to take adequate measures to ensure the data they collect is protected from misuse.

Compliance with the various disability and data protection laws of different countries is a difficult issue. In a borderless media like the web, deciding which country has jurisdiction is difficult to establish. For example, if the website of an Australian company that is hosted in Hong Kong is sued by an American user, which country’s laws will apply? The creation of a common law framework for the Internet can provide a simple solution to the problem.

Corporate websites now have to comply with the changed Companies Act that was passed into law on the 1st January 2007.

Copyright protection in web publishing can be classified into two categories. One category is the copyright protection of your content, and the other category is the copyright protection of other’s content. The web developer should make sure that others do not use the copyrighted content without permission. A web developer must also exercise due care and avoid infringing other people’s copyright by using their copyrighted content without permission. Copyright laws vary widely between countries. According to Kingston University in London, for copyright protection in the United Kingdom, there has to be some “skill, labour and judgment” used in the creation of the work. In the United States, copyright protection is automatic.”

Commerically available software such as AeroTags TagsLock Pro can protect website content from unauthorised copying by encrypting the content of the web pages and hiding the source code of the HTML and XML documents.

The web developer must ensure that the content on the website, both text, images, and video or audio media are original, and do not infringe on copyrights. It is wise to obtain a written copyright release or written permission when using texts, stock photos, or graphics created by external agencies.

Ethical issues in website development can cover a lot of ground. Some of the possible areas where ethics are involved are:
• Ensuring that the web content does not infringe anyone’s rights or cause offence
• Ensuring that the ideas espoused by the site are ethically sound
• Using ethical principles in search engine optimisation
• Ensuring that all users can access the site
• Requesting permission before linking to other sites
• Avoiding deep linking by bypassing the homepage of other sites
• Avoiding the use of any malicious code in the site that might cause harm to the user’s computers or communication networks
• Taking reasonable measures to ensure that the site cannot be not used by hackers to launch attacks against other websites

This list is not comprehensive, and you can add or subtract items to suit your specific needs.

5.1 Economic considerations

When  the economic viability of a website, consider the costs versus benefits, or development and maintenance costs versus the revenue. In general, given the proliferation of websites on an astronomical scale, one can conclude that at least several thousand low cost websites are being created a day. This can be considered proof that websites are generally cost-effective and viable.

6.1 About the author

Kris Weylo is a technical writer with over 20 years of experience in the IT/software, financial, medical, hardware/electronics, optoelectronics, engineering/marine and aerospace sectors. During this time, Kris has written documentation for various levels of users, delivering them over media such as e-learning modules, data modules, help kits, online help, intranet, and print. Kris has also managed geographically distributed projects and authoring teams to successfully produce the deliverables within time and budget.  Kris is currently writing his thesis to complete the final year of his Masters degree in Technical Communication.

Kris has a keen interest in identifying and applying new technologies to enhance technical writing.

Possibly related articles:

1. From Information Development to Knowledge Development
2. The Value of End-User Surveys in Testing Landing-Page Usability
3. Applying Business Process Principles to Information Design

By Manjusha Nair

As technical writers, we rely heavily on design documents and prototypes to get an understanding of the product/software; the absence of this basic arsenal can stump the best of writers. But there are alternatives…

We discussed in the last article how agile does not follow any pre-determined process, and does not rely on documentation (internal specifications documents). For a technical writer coming from the traditional waterfall scenario, it is perceivably daunting to start work on such a project. Let’s look at the requirements gathering process that works best in an agile environment.

Getting started

A good starting point is the user story. Look at it to understand whatever you can of the size, nature, and complexity of the feature you are documenting. Once you’ve read the user story, you will undoubtedly have questions. This is a good sign – you must immediately start asking these questions. The sooner you get answers, the sooner you can start writing the draft.

The power of meetings

Kick the old waterfall habit of relying on the design documents and start relying on one-on-one interaction and impromptu meetings instead. Scrum team members usually sit close to each other, which is a blessing for the writer, who does not have to chase elusive SMEs over chat and email.

Don’t wait for developers to respond to your email requests. Just visit them in their cubicle, and have quick meetings to resolve doubts and get clarifications.

You will be meeting your scrum team everyday for the ‘daily stand up meeting’, which is is nothing but a status update meeting where each member of the team talks about what they did yesterday, what they are doing today and whether there’s anything blocking them. Articulate any problems you may have in the daily scrum meeting; make use of this meeting to bring up anything that you may need from any of the scrum members.

Agile works best if all members of the team are co-located and most organizations make an attempt to co-locate their agile team members. This is how everyone has access to their team almost constantly. This ensures that work carries on as per schedule and everyone is on the same page. That said, you may be working with a team member in another location (onsite/offshore). In such cases, fixing up a set time to interact and get clarifications would work best.

Keep records for tracking

Keep a document/notepad/spreadsheet in which you record everything. Because things are happening on the fly, it’s very difficult to keep track of everything if you just commit it to your memory.

Always send MOMs after meetings, even if it’s an impromptu one-on-one. This might take a few minutes of your time, but will keep everyone sane in the long run.

I use different colored cells in a spreadsheet to track the requirements. Sometimes developers are not sure of the feature and will ask for some time to figure it out and get back to you. Mark these things in your tracker and go through it before every stand up meeting, so you can bring up anything that’s blocking you.

Even though initially daunting, agile actually works well for a writer gathering requirements. Agile lets you form close networks with your team: be proactive, friendly, hold your own, and in the end this methodology will not fail you. Proximity to the SMEs and meeting them every day will perhaps work even better than the traditional waterfall projects ever did.

In the next article in the series, we will discuss developing documentation in the agile environment.

About the Author

Manjusha Nair is a content specialist working with Infosys, Bangalore. She is passionate about innovation and sharing knowledge. In her spare time, Manjusha likes to write poetry and fiction.

Possibly related articles:

1. Planning for AGILE
2. Developing documentation for agile

By Devika Ganapathy

A few years ago, I worked as a usability specialist at a large technology and services company based in Bangalore. The design unit at this company comprised a large team of nearly a 100 people – mainly interaction designers, but also several visual designers, information architects and technical communicators.

At the time I worked there, several new systems and best practices were being put into place. It was also the time a small usability team had been formed, and one of the mandates of this team was to inculcate a culture of iterative design and systematic design feedback among the designers. The idea behind doing this was to ensure a ‘basic’ quality standard on all User Experience (UX) projects going out of the design unit. A second agenda was to improve skill sets and design sensitivity of junior designers / designers new to the team.
One of the ways in which we set out to do this was through a peer-peer design review system – Essentially a modified Expert Review practice designed to suit the specific context:
For the system to be successful, it was imperative that the reviews were objective. (Personal opinions / pointing out issues that could not be justified convincingly would become the recipe to disaster! After working hard and passionately on a design, the last thing a designer would want to hear is baseless or subjective criticism.)
It was also important for the process to be quick and practical (Issue identification, iteration and dialog oriented vs. presentation focussed) since the design teams were typically hard pressed for time and often managing multiple projects and deadlines simultaneously.

Initially review teams were made up of 3-4 interaction designers ranging in seniority per team.
The system having demonstrated a perceptible improvement in quality of work, we decided to experiment by introducing a diverse perspective into the review team.
So in addition to the designers on each review team, a technical communicator (TC) was also included.

The reasons behind choosing a TC to contribute to the review team were many:

• Focus on User EXPERIENCE vs. User INTERFACE – Content is a big part of the overall experience – Both in terms of stand-alone or complimentary documents and systems + content that is closely integrated with and into the main interface.
• Technical writers were not coming in cold – To start with, they would already have a basic sensitivity and understanding of usability issues since many of them worked closely with design teams and often had to include workarounds and explanations for poorly designed systems into their documentation.
• They were already familiar with the system and practice of ‘peer-review’ in context to documentation. Several TC guidelines and heuristics are available online and used in peer-peer documentation reviews. For Example:
  • http://www.stcsig.org/usability/newsletter/0004-docsheuristics.html
  • http://www.niar.twsu.edu/humanfactors/toolbox/Heuristic.htm

Some valuable lessons emerged out of this experiment:

• Starting with a simple checklist based Heuristic Review (vs. an Expert Review which can include multiple heuristic checklists as well as countless design principles, guidelines and best practices) proved to be a more systematic way of introducing TC’s to the usability review process. Expert review skills can only be built up / internalized through years of hands-on experience.
• In addition to these fixed usability heuristics, it was most productive for TC reviewers to focus on labelling, wording and content related issues initially, rather than attempt to immediately start reviewing UI aspects like navigation, layout or visual design.
• A verbal discussion / presentation of review findings proved very useful to both the designer whose work was being reviewed as well as to the reviewers:
• Having a dialog around the issues identified through review helped designers understand the issues more quickly and served as a useful way to get buy in from the designers.
• Sensitivity and understanding of unfamiliar issue types (UI specific issues for the TC reviewers and content related issues for the UI reviewers) could be developed over time, by listening to the discussions around the different issues identified by designers and TC’s in context to the same application.
• Hearing and seeing issues through discussion helped get new / below average reviewers up to speed.
• TC’s with previous experience working with design teams / a basic understanding or previous application of generic UI guidelines performed better than TC’s who were fresher’s or even more experienced TC’s who had restricted themselves to usability guidelines specific to writing.

An interesting observation was the difference in perspective between a TC and a designer in identifying issues.
Even prior to introduction of TC’s into the review team, the UI designers were required to identify issues in content and wording as part of their overall usability review.
However, when compared, there was a distinct tendency for designers to focus on and be able to catch a certain type of content issue, as compared to the type of content issues a TC intuitively highlighted.
For example, issues related to ‘Readability’ (Font type, size) were a common issue identified by UI designers.
On the other hand, TC’s typically highlighted issues like ‘usage of active vs. passive voice’ or ‘usage of consistent writing style through the system’.

On the whole, the experiment of introducing TC’s into review teams helped to demonstrate that a designer-TC review team works well and is beneficial to both professions:

• TC’s experience and aptitude for clear and concise writing helped to communicate more clearly, compellingly and quickly, the issues and recommendations the designer identified. (The impact or implication of issues identified by designers was sometimes lost because of poor written communication skills)
• Discussions with the designers around how a wording issue impacts UI / UI context and usage helped TC’s to gain additional insights into the nuances and feasibility of fixing a wording issue within a larger UI context.
• Getting involved in the process earlier on helped the TC’s to weed out issues that they might otherwise have only been able to address as a work around / explanation in their help documentation.

In context to the emerging trend of closer integration of help into the main interface design (vs. a separate help document), a better understanding of UI design and awareness and application of usability methods is a skill that would be beneficial to the TC community.
Training TC’s to conduct heuristic reviews (and over time expert usability reviews) appears to be a good way towards doing this.

Related Reading:
An article titled ‘Overlap, Influence, Intertwining: The Interplay of UX and Technical Communication’ from the Journal of Usability Studies (JUS) explores the relationship between the two disciplines and questions roles that people with technical communication training have (and could have) within user experience.

About the Author

Devika is the founder and principal researcher at Anagram Research and conducts usability and research studies in the areas of personal computing, mobile devices, messaging and Internet experiences. Prior to this, she worked at varied technology and research environments like Yahoo, Infosys and Human Factors International.

Possibly related articles:

1. 7 Habits of Highly Effective Technical Communicators
2. Technical Communicators in India Next

Vol XIII, Issue 3

As we enter the second half of year 2011, we are glad to bring you yet another edition of STC India’s newsletter, INDUS. We value your continued feedback on our newsletter and welcome your participation. Do not forget to post your comments and to send us your ideas for the next edition of the newsletter.

In this edition, we have some very interesting articles on various aspects of technical communication. Well-known expert, Larry Kunz, shares his perspective on the technical communication trends. Kris Weylo sets forth the design aspects that revolve around website development and Devika Ganapathy advocates that technical writers can don the role of heuristics reviewers with better understanding of UI design and usability methods.

Experts Ignite this time features Sairaj Vaithilingam, who leads the Content and Design Services (C&DS) practice at Cognizant Technology Solutions. Lori Sanders says that motivation, hard work, and commitment are the essential skills required for a successful career as a contract technical writer. In the second article of the series on Agile, Manjusha Nair explains how crucial the requirements gathering process is in an agile environment.

Suchitra Govindarajan attended the first-ever STC India Summit in Bangalore and decided to sends us her thoughts on the event. And Rajdeep Gupta, STC India president, mulls over what really drives technical communicators like us to work. Rajdeep also drops hints about an upcoming event. Watch this space.

As usual, we have a few News and Notes from STC India.

Enjoy reading the monsoon edition of INDUS. We hope that you find this edition interesting and informative.

- Anupama Gummaraju and Sreeraj Nair

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

Possibly related articles:

1. Mar-Apr 2011 Newsletter
2. July – August 2011 Newsletter
3. September – October 2011 Newsletter

• My STC Network is a platform for for networking, collaboration, communication, community management, and more. It combines the knowledge-sharing capabilities of a professional network with the interactivity and user experience of a social network. To experience the My STC Network, please visit this announcement.
• The members, who renewed their STC membership for 2011, were promised two free archived seminars, from the 2009 Technical Communication Summit. However, STC is celebrating this offering in style by offering all 38 archived seminars for free! Once you are logged into stc.org, click this link.
• Tales from the Summit are great and too many. The new awards, introduced at the STC Honors Banquet, are listed here. The list of new associate fellows and fellows is here. Almost all of the 80-plus sessions at the Summit were recorded, and SUMMIT@aClick offers them at a nominal price. The photos from the Summit are up on the STC Flickr site.
• Due to the overwhelming response to the April issue of Intercom being open, STC has made the May issue of the magazine open to the public. Please share this news with interested colleagues, and be sure to invite them to join STC so they can get this kind of quality publication all year long!
• As you’d remember, at the STC Annual Business Meeting, Hillary Hart was officially installed as President and Alan Houser as Vice President of STC. Short video interviews with Hillary and Alan are captured here.
• Two communities and two members of the STC staff recently were named winners in APEX 2011. APEX Awards are based on excellence in graphic design, editorial content, and the ability to achieve overall communication excellence. Read more here.
• A new certificate course titled ‘DITA from Legacy to the Future’, presented by Bernard Aschwanden, is added to the schedule. More details are here.
• Submit your nominations for STC office for 2012. Either nominate yourself, or someone else you feel would make an excellent society-level officer. The election page has further details.

Possibly related articles:

1. STC Announcements
2. STC India News & Notes, March-April 2011
3. STC Announcements

As each work day comes to a close, I find myself thinking about the everyday work we do, comprehending new systems, understanding new users, communicating with varied audiences, arguing our way over hinderances, and managing to perform multiple roles as technical writers.

At a first job, or a new job, there is enthusiasm, gusto, and an eagerness which may fade, if there is too much of any one of the above! I still cannot forget the day of my first interview, the passion, the eagerness that I had to start afresh. It’s something that I will personally try to keep alive. How do we sustain what is motivating and fun in our work lives?  There is no one single answer, but some of the contributors in this edition of Indus give us insights into redefining the job, learning new areas of work and keeping the spark going. I hope you will enjoy this edition.

STC India’s calendar has also been quite eventful the last two months, with STC India conducting its first Summit at the Chancery Hotel on the May 7 and 8. 150 people attended this two-day event. Click here to download the Summit presentations.

We are planning to organize our first User Experience and Usability conference in the last week of August in Bangalore. Stay tuned for the updates on our newsgroup and portal.

Finally, we are in the middle of 2011, and I’ld like to thank all our STC India volunteers for their contribution so far. Keep up the good work team!

Possibly related articles:

1. Prez Talk
2. Prez Talk
3. Prez Talk

My STC Network is a platform for networking, collaboration, communication, community management, and more. It combines the knowledge-sharing capabilities of a professional network with the interactivity and user experience of a social network. To experience the My STC Network, please visit this announcement.

The members, who renewed their STC membership for 2011, were promised 2 free archived seminars, from the 2009 Technical Communication Summit. However STC is celebrating this offering in style, by offering all 38 archived seminars for free! Once you are logged into stc.org click this link.

Tales from the Summit are great and too many.

• The new awards, introduced at the STC Honors Banquet, are listed here.
• List of new associate fellows and fellows is here.
• STC President, Hillary Hart talked about the Summit here.
• Almost all of the 80-plus sessions at the Summit were recorded, and SUMMIT@aClick offers them at a nominal price.
• The photos from the Summit are up on the STC Flickr site.

Due to the overwhelming response to the April issue of Intercom being open, STC has made the May issue of the magazine open to the public. Please share with interested colleagues, and be sure to invite them to join STC so they can get this kind of quality publication all year long!

As you’d remember, at the STC Annual Business Meeting, Hillary Hart was officially installed as President and Alan Houser as Vice President of STC. Short video interviews with Hillary and Alan are captured here.

Two communities and two members of the STC staff recently were named winners in APEX 2011. APEX Awards are based on excellence in graphic design, editorial content, and the ability to achieve overall communication excellence. Read more here.

A new certificate course titled ‘DITA from Legacy to the Future’, presented by Bernard Aschwanden, is added to the schedule. More details are here.

Submit your nominations for STC office for 2012. Either nominate yourself, or someone else you feel would make an excellent society-level officer. The election page has further details.

Possibly related articles:

1. STC India News & Notes, May-June 2011
2. STC Announcements
3. STC Announcements

Vol XIII, Issue 2

Four months have passed since the new year and new team working on another challenging year for the STC India newsletter! Thanks to those who wrote in commenting on the articles or via e-mail. Keep the feedback rolling in, we appreciate it!

We have some exciting articles in store this edition. The technical writing landscape is changing as we speak and new trends are changing the way we approach communication. We bring you Paul Trotter, CEO of Author-it, and his views on help authoring tools and trends. Manjusha Nair writes about planning for successful documentation execution in an Agile environment and Radhika P.C speaks about applying Lean Six Sigma principles to documentation. Manjula Kandula shares some ideas on the essential skills required for writers.

STC news and announcements keep you updated on what’s happening in India on the STC front.

The message from the STC India Chapter President, Rajdeep Gupta, is here.

We hope you find this edition informative and continue to contribute, make Indus a preferred publication for the technical writing community.

- Anupama Gummaraju and Sreeraj Nair

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

Possibly related articles:

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

With much accelerated demands in the global market place for customer-centric solutions, Customer Experience (CE) has become the buzz word that floats around most boardrooms and corporate training rooms. One methodology you might hear associated with CE is Lean Six Sigma (LSS). While CE directly focuses on customer satisfaction, LSS emphasizes process improvement, which in turn results in improving most areas of customer satisfaction. With documentation being a highly visible aspect of any product, enhancing documentation has found a significant place in the priority list of most organizations in order to win and retain customers. This article attempts to look at the various opportunities a documentation team encounters to improve the documentation and allied processes in order to gain better customer acceptance, both internal and external, in a short time with fewer resources—consequently, creating more  value for the organization with minimal $-factor involvement.

What is Lean Six Sigma?

As its name suggests, Lean Six Sigma (LSS) is a combination of Lean methods and Six Sigma approaches.

Lean = Speed     Six Sigma = Quality

LSS strives to quickly achieve quality from the perspective of the customers.

Lean is all about customers—Lean eliminates waste and complexity, thus creating more value in the eyes of the customer with less work. While Lean centers on the separation of ‘value-added’ from the ‘non-value-added’ activity and focuses on rapid problem solving, Six Sigma seeks to reduce process variation by identifying and removing the causes of defects. It provides two problem-solving frameworks called DMAIC (Define-Measure-Analyze-Improve-Control) and DMADV (Define-Measure-Analyze-Design-Verify)  that improve performance and productivity.

However, Lean or Six Sigma alone cannot achieve just quality or speed, or dramatically improve process speed or reduce invested costs. When Lean methods and Six Sigma approaches are combined, it can achieve the fastest rate of improvement in customer satisfaction, cost, quality, and process speed.

Defining Waste in Documentation

In a typical Six Sigma methodology, defining waste is not limited to the non-value added activities, but the project goals, scope, customers, and deliverables. In this article, the attempt is to find waste in documentation from the customer’s point of view by acknowledging the fact that the customer perspectives cannot be deciphered unless one clearly understands customer needs.

Therefore, anything in documentation that is not desirable to the user is considered to be waste or non-value added. To lean the documentation and allied processes, you must first identify waste and minimize it in the system.

Waste in documentation is classified into two categories—non-value-added content, and non-value-added activities in the documentation development process.

Non-Value-Added Content: Lengthy, Irrelevant, and Complex Content

“When everything fails, read documentation” is the popular belief. When everything fails, undoubtedly, users will be frustrated and will want to find the information quickly to resolve their issues. If the document they are looking at is lengthy and overly complex, it adds fuel to the fire—unhappy customers could eventually lead to shrinking revenue—a very depressing outcome!

Lengthy documentation adds complexity and hampers the very purpose of providing the documentation in the first place. Different technical writing team members or other teams that handle different components of a large product work in silos and write separate documents about the same features. The documentation effort is not well coordinated among these different teams. Often, we assume that users know everything and ignore the big picture (system approach) of the product. Sometimes, we write about everything except the practical action that the users must take. The result is, several documents addressing the same issues with tons of redundancy – yet not meeting the customer needs.

Nobody, including the approvers, wants to go through overly complex and redundant documents simply because they are too long and tedious to review. If the documents are not properly reviewed and approved, they will contain inaccuracies. Inaccurate documents do not serve any purpose other than intensify customer frustration.

Non-Value-Added Activities: Complexity or Lack of Process

Both complexity and lack of process almost equally harm documentation development. Carrying out processes with the wrong procedures, often when a simpler approach is more effective, adds complexity and involves extra effort from the resources. No development can be carried out successfully without well-defined goals and procedures. When establishing a new process, use the DMADV instead of the DMAIC approach.

Measuring Waste in Documentation

By using Six Sigma approaches, you measure the current process to determine the performance loopholes or establish a value-added process. To measure the waste, you can look at the documentation in two different ways—in terms of content and in terms of the documentation process.

Non-Value Added Content

The aim of a writer is to develop documentation that is relevant to the context, and more importantly, be usable and searchable. The biggest failure in documentation is the existence of redundant statements.  Determine whether or not a document or sections or words in a document add value by asking:

• Does anyone really read this section of the document?
• Is the documentation sufficient to perform the job?
• Which tasks do you think are the most challenging?
• How often do you refer to the documentation to perform tasks?
• Are there any tasks for which you always refer to the documentation?
• Which tasks require the most in-depth information?
• What is the most frustrating experience with the documentation?
• Is this section redundant? Can I just refer to another document or another part of this document that already states the same information?
• Am I really reviewing this document or am I just signing off a review hoping that other reviewers review the document to ensure its accuracy?

Based on the answers you get, structure, add, or delete the content to develop lean documentation.

Non-Value-Added Process

Any non-value-added activities provide a negative return on investment. Various studies in this area, some of which are described in the book Lean Six Sigma for Services, by Michael L. George, show that non-value-added activities account for 95% of the total lead time, of which 35% is necessary, known as Business Value Added – non-negotiable waste—an activity that is required to operate the business but the customer is unwilling to pay for—training, status reports, etc.

In a typical DDLC process most non-value-added activities, such as multiple rounds of reviews and rework in each phase, lead to duplication of work to the organization. It’s frustrating to everyone, it’s a waste of money, and for the writer it’s irritating and demotivating. Duplication of work typically stems from ineffective process flows.

Nobody can explore the non-value-added activities within DDLC better than the documentation team itself. You can analyze the process through direct observation, interviews, and surveys shared within the team. This kind of research can pin down the differences between how different resources perform the same task and the variation. In doing so, it is important to acknowledge that value is subjective—value is highly dependent upon the perspective of the multiple stake-holders. Indeed, in operationally defining value, consider the perspectives of end users, developers and QA, sales and marketing, and technical support who understands the pulse of the end users as well as the product under scrutiny.  Create an as-is representation and attempt to map each step to the points you have filtered through the survey or studies. While designing the new approach, it will ensure that existing problems are not duplicated.  Information about customer comments and complaints, defects, and post-project survey comments can be quite valuable at this stage. The primary purpose of this activity should be to optimize the work processes.

Analyzing Waste in Documentation

According to Lean principles, there are at least seven categories of waste that an organization must be aware of and work towards minimizing or eliminating it. Transport, Inventory, Motion, Over-Processing, Over-Producing, Defects (Tim Wood).

Let’s try to look at Tim Wood from the documentation perspective and create an as-is diagram to analyze waste in the DDLC process.

Improving Documentation by Waste Reduction

Lean is a continuous improvement system and aims to  enhance the value in the eyes of the customer, both internal and external. To do this, you must understand and view the whole system through the eyes of the customers in order to meet their needs. Producing what customers want, when they want it, and at the price they are willing to pay.

How to Minimize Transportation / Motion?

How to Minimize Inventory?

How to Minimize Waiting?

How to Minimize Over-Production?

How to Minimize Over-Processing?

How to Minimize Defects?

Controlling Waste in Documentation

Foster a culture where you continually improve your skill levels and documentation processes.

Discourage all kinds of non-lean behaviors— lack of teamwork, marginal motivation of workforce, team putting effort into insignificant matters, superiors not providing a sense of direction to the workforce.

Closely monitor the tasks with high work-in-progress (W-I-P) such as reviews, reworks, and approvals that leads to long process time; strive to remove bottlenecks and delays to those tasks.

Quickly resolve the defects that cause rework and increase the W-I-P—note that reducing the defect rate will directly reduce the rates W-I-P.

Take up the activities with the highest queue time first to reduce the lead time and W-I-P as the bottleneck is minimized or resolved.

Too many project responsibilities on the same resource often create significant complexity to the entire system. Level the workload, no idle, no over burden! Encourage your team to share the work load during the high workload period.

Reduce interruptions to high set-up time activities (setting up product environment) so that processing can complete without such interruptions. Seek assistance from experts to quickly finish the activities. Also, ensure that you document the steps or important points while doing it so that next time you can do it with any help.

Use checklists to track and follow process variation.

Capture the errors that are repeated, and ensure they are not repeated.

Convert the tacit knowledge (knowledge known to single resource of the organization—through exposure or experience to certain situation) to explicit knowledge (articulated or stored in a media).  Capture and maintain internal and external explicit knowledge.  Keep the team’s explicit knowledge base up-to-date.

About the Author

Radhika PC, a Senior Technical Writer with EMC Corporation, brings in more than 7 years experience in different flavors of Technical Communication including IT Journalism, Courseware Development, Science Journalism, and Software Documentation. A Gold-Medalist in MA Mass Communication & Journalism from Mysore University, Radhika has a degree in Computer Science. She is a Lean Six Sigma Yellow Belt holder, and currently pursuing Project Management & Communication Certification at Indian Institute of Science, Bangalore. Radhika is known to be an open-source enthusiast.

Possibly related articles:

1. Applying Business Process Principles to Information Design
2. Applying the Wideband Delphi Method for Estimating Documentation Effort
3. Publish-As-You-Write Model for Documentation

Agile has become a popular and widely practised method of software development that it is here to stay. Since agile development is so different from traditional software development methodologies, technical communicators need to adapt to keep up with the pace and style of agile development.

HOW DOES IT WORK?

A lot has been written about agile, so I will keep it simple. It is a method of development where a small group of people work collaboratively to achieve set targets in a set span of time; generally a 3-4 week sprint or iteration. The most widely used agile method is the SCRUM method.

Shorter iterations are better. If the cycles are longer than four weeks, then old habits of working with the waterfall model will start to creep in.

The agile team is a self-organizing, cross-functional unit that works closely, meets often, and does not follow any role-hierarchy – the Scrum Master’s role is just to coordinate meetings and remove hurdles if and when team members report them.

A scrum team typically consists of developers, testers, and a technical writer or two. The maximum size of the team is generally 5-10 people. Any more than this, and agile doesn’t give the desired results. This is because it does not follow any pre-determined process, and does not rely on documentation (internal specifications documents); so it becomes rather difficult to keep too many people on the same page.

Features, broken into achievable units called user stories, are picked up by the team to work on, based on the time each member has on hand. Each of these user stories is developed, tested, documented, and delivered in a set time (sprint).

PLANNING FOR AGILE

The key difference between planning for an agile project and planning for a traditional project is that agile project planning is a collaborative activity. The whole team participates in planning, not just the project manager. Each member of the team, including the writer, is involved, and provides inputs for the master plan of the project. And each of these members is responsible for planning their respective tasks once the high level plan is in place.

With no mandatory internal documentation and no processes, agile can get very chaotic for a writer if not planned and tracked well. Here is how you can induce some semblance of order into the proceedings:

• Shorter iterations are better. If the cycles are longer than four weeks then old habits of working with the waterfall model will start to creep in.
• Always look at the requirements (the user story is a good starting point), and talk to the feature owners and developers to understand the feature.
• Run through all the tasks involved and make a rough estimate of how long it will take for you to write the feature.
• Check dependencies. Does it need to refer to another document? Does it require knowledge of another feature? Add more time to your estimate if it has dependencies.
• Include details of what you will deliver at the end of an iteration (for example, a basic draft, or an intermediate draft with SME comments incorporated). This makes it easier to track. Also, plan when in the iteration you will be able to share a draft with the engineering team.
• If you are going to be on leave, build that into the plan and mention the dates.
• Check how much time you can devote to the project. In a utopian scenario, a writer will work in just one scrum at a time, but that is as far from reality as Utopia is from your current abode. Prioritize activities in your various scrums to arrive at a workable plan. It could be 2-3 hours every day or two days in a week, depending on what works for you and the team.
• Always keep some buffer time to accommodate last minute changes when you draw up the estimate*.
• Discuss the estimate with the team and arrive at a consensus: should documentation be a separate user story? Or a task/child story within a development user story?
• Explain to the team that you will need their help and support because documentation is an essential piece of the user story puzzle – the feature is not considered complete till documentation is delivered.
• Make sure that your suggestions and estimated times are present in the master plan.

If you keep these pointers in mind, agile can be one of the best methods you can work with. It is interesting, challenging, and keeps you on your toes.

Do remember that even though you have planned well, agile is agile; you should expect changes. Sometimes, features will change course in the middle of a sprint. Keep checking if you can accommodate the changes. If not, suggest that the changes be another user story to be taken up in a subsequent sprint.

The next installment in this series will talk about requirements gathering in an agile environment.

*The engineering team may create small specifications documents for their reference; these might become available to you sometime during the sprint. The testing team’s inputs, which typically come towards the end, might also lead to changes in functionality. Plus, you will probably get the first look of the UI towards the middle of the sprint. Considering that you have already been working on the draft, these events obviously require you to make changes to the documentation. Also, technical teams sometimes take the ‘known defect’ route to beat time. In other words, they may ask you to include a few notes or caveats, because there is no time to fix the issues in the build.

Manjusha Nair is a content specialist working with Infosys, Bangalore. She is passionate about innovation and sharing knowledge. In her spare time, Manjusha likes to write poetry and fiction.

Possibly related articles:

1. Developing documentation for agile
2. Requirements Gathering for Agile

When I was a science journalist earlier on in my career, a good friend invited me to join a leading software company as a technical editor. I began to weigh the pros and cons of staying or leaving the Fourth Estate.

I reasoned to myself that being part of the Press was challenging and offered me a dynamic environment. Being in constant touch with leading scientists, science-policy makers, politically inclined scientists, and analytical politicians kept me on a constant high.

On the downside, the newspaper industry has sharp deadlines, keeps one under constant scrutiny of the public. Working with clunky tools (in those days) meant that pages vanished from systems at the ‘drop of a vowel’.

I did make a move into the IT industry as a technical editor. They say that ignorance is bliss and I was in the throes of it! I took the plunge little knowing that there were sharp deadlines to meet and late night calls to reach out to the remote teams. After learning a smattering of UNIX and serenading the style guide, I quietly plunged into the coding zone.

Now, several years have gone by and I have moved from editor to writer to manager to consultant, as per the dictates of the job (or lack thereof), growing interest or a changing need.

The  growing pool of technical writers rely heavily on being able to articulate well, understanding the demands of changing technology,  relating to clients and customers, speaking the product language, and being adaptable to the esoteric corporate culture.

If the technical writer of the past carried a compact kit of skills, today this kit has turned into a knapsack. At a very fundamental level, the technical writer must have good language skills which are the bedrock of good documentation. Yet I know writers who, even today, quietly ignore the red marks of the spellchecker, and bulldoze their releases despite gunky grammar. That’s strictly taboo. You cannot reach your destination by skipping parts of the path! All documentation tools come equipped with language and spellcheckers, and writers are encouraged to use them, if not for their own sanity, at least for that of their reader’s.

Good writing is only one part of good technical communication. Today technical writers have to use novel ways of gathering as much pertinent information as they can, before they start writing. For this, they need to know where to find information, and collate questions on the topic that they are documenting.

A unique challenge for technical writers today is the ever-increasing features being built into software products. Companies are scaling dizzying heights to please their customers. Even as a writer completes documenting a feature, the engineering team approaches the writer with a request for change. It could be in response to the demand from one customer or several customers. The growing competition is making companies reach out to as many clients as possible and cross the Finish-line well ahead of their competitors.

All this certainly comes with a price tag. For a writer, it’s a fine balancing act between the internal teams and their external users. Are the users as happy with the documentation as they are with the product? Writers will do well to garner feedback from support teams, over documentation. They might even want to create a process for this type of information gathering, if such a process does not already exist in the organization.

At the Indian Institute of Science, we recently designed a questionnaire for leading entrepreneurs in Bangalore. The aim of this project was to understand the growing entrepreneurial ventures in Bangalore from a social, technological, and economic perspective. The questionnaire looked good to us as it was replete with pertinent questions. However, when we did a field survey, meeting entrepreneurs face to face and presenting them with the questionnaire, several entrepreneurs complained that it was too verbose, cumbersome, and even disjointed in a few places. Clearly, there was a gap between what we sought from our users and what the users themselves wanted. So we have gone back to the drawing board to simplify and re-organize the questionnaire.

One cannot overemphasize the need for research, analysis, and interpretation of information, not to mention etching out a sensible documentation plan before hitting those computer keys.

The tools, methodology, and medium of communication used are also undergoing a dramatic evolution today. The pre-publication process (or production process), often seems daunting for new writers. Often enough, documentation teams build on a methodology by adding a train of tools that ‘talk’ to one another in typical tools-based jargon. For example, if you have moved to DITA methodology, you will have to understand the workings of a tool like X-Metal. Your team might also migrate to a new Content Management System (CMS) suiting the new methodology, understanding how topics are stacked, organized and combined into DITAMAPS.

Writing concepts, tasks or procedures also needs a clear understanding of how to group or chunk information. So information ceases to be linear and moves into a higher order of semantic sorting and mapping.

Information has suddenly become multidimensional in many ways. If information mapping is one paradigm, you also have different channels for putting out information, or broadcasting it. From blogs, YouTube videos, forums, Tweets, Facebook fan pages, social media has unfolded a whole new way to massage and present information.

Writers today need to change styles quickly to suit these channels of communication. Writing for videos has to be brisk and clear. Blogs have a certain refreshingly free style to showcase your products. A quick Tweet to announce a new release has a wide reach and enjoys quick response. Social media flattens hierarchy in an organization- for writers and CEOs use the same platform for showcasing information.

Wiki pages pave the way for a very interactive method of gleaning documentation.  Author and user roles have suddenly become interchangeable and it’s a totally new-fangled learning ground that we see out there.

Ultimately, writing is all about reaching out to people and making a connection. If you’ve ‘clicked’ with your users, it’s probably not merely because of one particular method or medium that you have adopted. It’s much more than that, and I’m still trying to figure it out. Good writing is like making good pasta and serving it up piping hot. But great writing is like topping your pasta with a million scraps of Mozzarella cheese to give it that ultimate zing…

Author’s bio:

Manjula Kandula is a  a part-time communication consultant at EMC and at the Indian Institute of Science, Bangalore. Manjula specializes in content development, which includes both writing (white papers, market collateral) and editing, and has been in the technical writing industry for over ten years.

Possibly related articles:

1. Do Indian Technical Writers Need Professional Courses?
2. Managing Engineering Writers
3. Decoding Science Writing

As part of STC India Chapter’s initiative to collaborate and work with various international technical communication professionals and experts in the field of technical communication teaching, the STC India Admin Council has decided to hold tech communication webinars.

STC India Webinars

Top 10 Grammar Problems, Complaints or Opportunities

Dr.Rolan Nord is a senior member of STC and teaches technical communication at the Minnesota State University. In his webinar, Top 10 Grammar Problems, Complaints or Opportunities, he provided us with a quick refresher course on  issues in American English usage. Dr. Nord covered topics such as  grammatical errors, grammatical mistakes or problems, and strategies for editors to deal with such errors or problems.

The webinar was conducted on March 26, 2011.

Essentials of Instruction Writing

Dr. Lee S. Tesdell teaches courses in the technical communication program at Minnesota State University, Mankato.  His webinar provided us tips on how to structure a help topic, integrate images and text in instructions, and create bilingual instructions. Visit the http://www.stc-india.org/2011/04/recording-of-essentials-of-instruction-writing/ page, and click the link- https://umconnect.umn.edu/p25839587/?launcher=false&fcsContent=true&pbMode=normal to listen to the recorded webinar.

The webinar was conducted on April 2, 2011.

The Role of Readability Formulas in Technical Communication

In this interactive webinar, Dr.Nord conducted and provided an overview of readability formulas and their use with respect to technical documents and reviewed recent research (conducted within the past 10 years) on the same topic.

The webinar was conducted on April 9, 2011.

STC India Learning Sessions at Bangalore

A full-day learning session was organized in Novell, Bangalore, on March 26, 2011. In the session, Bindu Nayar and Triveni Mahesh talked about the world of estimation and took us through the process of estimation using the Wideband Delphi method.

Mridula Mukund’s and Premleela Radhakrishnan’s session on “Pulse Check of Doc Projects – Best Practices at Novell” highlighted the importance of effective tracking and reporting of documentation projects, and the pragmatic impact they have on improving the visibility of the project.

In their session,  Usability Counts, Shalini G and Sandhya Sriram shared some best practices, which can be applied effectively to enhance documentation usability. The session also aimed at discussing why documentation usability is important and how it can make a big, positive impact on the company and, most importantly, on the company’s customers.

The last session was conducted by Archana Narayan on Learnability Testing. Learnability testing is a comprehensive process that tests the instructional strategies used and usability of the course. The learnability testing session focussed on how to remove the obstacles that hinder the learning experience.

The fact that the sessions could be attended via WebEx had enabled more technical communication professionals’ to access and participate in the learning sessions, increasing the reach of the training programs.

The sessions were sponsored by Novell, and Technowrites, who facilitated the WebEx sessions.

STC India Learning Sessions at Pune

Shrirang Gokhale conducted a session on Balance Scorecard on March 19, 2011. The session provided insights into the Balance Scorecard, Fixing Targets and KPIs (Key Performance indicators), a method to achieve targets, add measurement factors to targets, allocate importance, tabulate, plan deployment and review, and much more.

The sessions were sponsored by Technowrites. Outstation participants attended the session using WebEx sponsored again by Technowrites.

STC India Annual Competitions for 2011

STC India Chapter is pleased to announce competitions in Informational Materials, Instructional Materials, Promotional Materials, and User Support Materials this year. It is time for you to display your talent! Exciting prizes await the lucky winners!

Send in your entries to competitions@stc-india.org by April 25, 2011. The Competition rules are available for your reference at: http://www.stc-india.org/2011/03/stc-india-competition-rules/.

Possibly related articles:

1. STC India News & Notes, May-June 2011
2. STC News and Events, Jan-Feb 2011
3. March-April 2010 Newsletter

Professional networking

For someone who has more than 600+ connections in a professional network LinkedIn, it sounds foolish when he says professional networking is a big waste of time. But there are certain myths associated with it, which is not true in today’s business climate. I share here  a couple of myths around professional networking and would love to hear from you about your experiences.

1. Meeting big prospective customers at conferences – Most people who attend these conferences and seminars are not decision makers because they are too busy with their professional assignments. And even if they do attend, vendors surround them from all angles. It does not mean that people from big companies do not network. They usually network at the community level and prefer to meet with their counterparts from various other divisions and converge at industry specific events and exhibitions.
2. Referring contacts- If you are looking to get introduced to a big-shot of a big firm, chances are pretty slim. Unless I have a better sense of your capabilities, character, and style of  functioning and so on, why would I risk introducing you to someone? If it turns out that the company to which I referred you finds you incapable, I stand to lose my credibility. Always make sure you know the professionals whom you approach.
3. Proactive approach- It takes a lot of time and perseverance to follow up on the contacts one makes at conferences and events.  Ask yourself if you have that time to spend.

Coming back to news and happenings at STC India, I am pleased to share  that the STC India Chapter has earned the Community Merit Award for 2010. The citation on our certificate will read: “For your active and enthusiastic efforts in providing opportunities for professional development with your Annual Conference, regional conferences, and Career Day”. Our Community will be recognized during the Leadership Day event on Sunday, May 15, at the summit in Sacramento. At that time,  we will receive the CAA certificate.

This is really a wonderful news for us because we had so many new volunteers, but our team work paid off to win us this award for our efforts. It’s really difficult to do a good job for work that is completely voluntary, in addition to our busy work schedules.

The 1^st STC India Summit is scheduled to take place at the Chancery Pavillion, Bangalore on May 7-8, 2011. We are conducting  5 workshops, 20 conference sessions, 1 panel discussion and lots more in the two-day summit. Take a peek at the Summit agenda here: http://www.stc-india.org/2011/04/summit-agenda/.  In case you are planning to attend, do visit the following url to register: https://spreadsheets.google.com/viewform?hl=en&formkey=dDl3SER0LW1oV19hdnV3Qm16cUNnRnc6MQ#gid=0.

In conclusion, our prayers go out to the people of Japan. On March 11, 2011,  an 8.9 earthquake struck off the northeast coast of Japan near the city of Sendai. The earthquake generated a massive Tsunami  resulting in floods and fires. Thousands of people were killed, and homes, fields and towns were flooded or destroyed.  You can use the STC India portal to make a contribution. Do visit the link- http://www.stc-india.org/.

- Rajdeep Gupta

Rajdeep is the President and Sponsorship Manager for the STC India Chapter 2011. You can write to him at president@stc-india.org.

Possibly related articles:

1. Prez Talk
2. Prez Talk
3. Prez Talk

• Leadership Day takes place on Sunday, 15 May, starting at 8:00 a.m. with coffee and then running from 8:30 a.m. through 4:00 p.m. with a break for lunch. All Leadership Day events take place at the Magnolia Ballroom in Sheraton Grand.

• For the draft schedule of the full day’s events, see the Draft Leadership Day Schedule.  The cost for Leadership Day is $20. If you haven’t registered for the Summit yet, you can sign up for Leadership Day when you register.  If you’ve already registered but would like to attend Leadership Day as well, please contact Julia O’Connor to process your payment.

• The Rochester Chapter of the Society for Technical Communication, in partnership with the Rochester Institute of Technology, is pleased to announce its annual Spectrum 2011 conference, Building Better Solutions: A Skills Symposium!

• STC is pleased to announce the results of its 2011 election. We had a total of 4,469 eligible voting members. A total of 853 voters used their ballot, amounting to 19.09% of eligible voters. The percentage voting was 6% higher than the previous years. We thank you for your participation.

• Rich Maggiani and Tricia Spayer have been elected as STC Directors while Alan Houser will be serving as the Vice President for 2011-12.

Possibly related articles:

1. STC Announcements
2. STC Announcements
3. STC Announcements

In the second edition of the Experts Ignite series, we talk to Paul Trotter, the Founder/CEO of Author-it Software Corporation and the architect of the Author-it product. Author-it was born out of the frustrations that Paul experienced producing documentation in the Telecommunications industry. His vision was to solve the problems that content writers face – not provide a cure for the symptoms. The result was Author-it; a product built from the ground up around principles such as topic based writing, single sourcing and separating content from format.

Regarded as a visionary within the industry, Paul is a popular speaker at events all over the world on topics ranging from technical writing and help authoring to content management and localization. Today, Paul continues to drive the product vision for Author-it. In this he applies his problem solving talents to the day to day issues that people face in creating, managing and delivering content. This vision has seen the development of world leading technologies such as Author-it Xtend and Author-it Live.

Could you share your experiences about your first technical writing job?

Yes, it was a long time ago now. I remember I was hired into work for a company that was producing a piece of software for managing hospitals and it broke up to a bunch of modules working on emergency room module. And they asked me to write a manual and gave me a Microsoft Word to do that with. And I was halfway through into the job, probably a few weeks, when they came back and told me “hey, we need an online help with this as well.” And they did not have any particular help in mind. And I said how am I  supposed to do that. And they said oh, here’s this, just plug in to Word and that will just convert the Word document to help.  It took me a few weeks to get it to work and there were a lot of things that I had in the Word file that I wanted to compile. And I said, “gosh there should be a better way of doing this.” And that is what led to the inspiration to create a tool that manages information better and is able to produce more than one format without having to sacrifice the capabilities of source files. And that was my introduction to tool sets in technical writing. I had come from an industry where there were lot of tools specifically designed and developed for your job and not tools that were kind of a bunch of macros someone put together without proper processes. That lead me to go back to understand what was the problem that I was looking into and eventually design something to solve this problem. And Author-it was formed.

How can technical writers learn about the ROI value they bring to their job?

There are couple of different types of technical writers from my experience – people that are more in the technical end and people that are more in the writing end. It really depends on where they come from before they arrive at technical writing. The actual degrees in technical writing and technical communication is relatively new compared to other IT disciplines so many writers the value that they bring to the role is when it is more technical side focused on tools or on technology behind the tools so they bring value in terms of their maybe their expertise in CSS, HTML or dealing with any particular technology. Then on the other end of the skull you got people who bring value to writing itself so maybe their technology expertise is less strong so they rely on each other to get the job done.

When you are measuring ROI in terms of product, then the ROI depends on the skill set that they bring. Most tools will create ROI by reducing the amount of labor required and Author-It is no exception to that. So we provide increase of efficiency and doubling of productivity. So how do you measure that? Basically you say I have got 10 writers. 10 writers are paid X dollars per year. If I double their productivity, than I can get twice as much as work and so the ROI that you see here is 50 percent of the value of the employment of those people can be redeployed and used for other tasks and most people when looking at technology they are concerned that a technical product is going to do them out of the job is not the case.

It has been my experience that, almost invariably, technical communication departments are overworked and under resourced for the work they have to do. What the tool does is merely allow them to meet their current deadline to current deliverables on their milestones without having to invest further and more and that’s the typical thing that we see.

So the other when you are dealing with a product that it takes away a lot of the technical challenges like Author-it does, we tend to hide a lot of the technology under the hood, it means that those people who are technical in nature will be able to refocus their expertise away from the toolsets and more towards maybe underline template design, and those people who are writers r is alleviate having to do with technology as usual the writer spent about 50% of their time dealing with formatting, layout and publishing type of activities. AIT almost eliminates all of those activities from the date they were the writer has for arm also one of the other are white whence you can get is the reuse of information so we typically see about a 30 to 40% reuse of information.

How is social media revolutionizing the communication channels? Can technical writers play a role here? If yes, how can technical writers integrate social media channels in their work?

Social media is revolutionizing many parts of our lives, not just in technical Communications. But Communications I think in a large way, as it is replacing or at least parts of e-mail communication started with the familiar texting and it has kind of evolved into the online chat, and to full-blown social media sites like Facebook, Twitter, MySpace and so on. Where we are going to see it going, in Technical Communication is this type of interaction that now allows people to collaborate and communicate quite differently from how they were used to communicating. It has certainly brought communities closer together so people in technical communication collaborate with peers and their clients in a much more real-time fashion. So one of the ways that we see social media is, it is going to play a role in a technical communication in the process of reviewing content, and when you think about the process of reviewing content it is very much a social or should be a very social type of task, where, if you sat together in a room and you went through a document together you then discuss the changes and agree and disagree on things.

So what we’ve tried to do with the is what our latest products Author-It Reviewer is to bring that whole element of social networking and communication like a Facebook or Yammer and bring it directly into the review process so that the new review product that we have is a real time social review. I think that is one way that you consider bringing in technology, so when one reviewer suggests a change about an insertion or deletion, other reviewers will be instantaneously shown the change in real time and will be able to have a Facebook-like discussion and agree on a change.

I was presenting at an event recently and I was asked “How will this kind of social media work with our clients?” and to be honest I see contributions from your client communities being very similar to a review process. After all, that is the way you end up getting contributions from your internal organization and why should contribution from your clients be any different? And we see that kind of social base commenting in reviewing as being a mechanism that can also be employed to get feedback on your documentation from your end-users. You can also employ mobile technology so that the changes made by one of your clients or suggested that changes automatically appears on your mobile, your iPhone, your Android. You pick it up immediately, approve it and back it up on your output without you having to go and change anything, so that’s where social media creates a real difference in the way that we are working. It allows us to have really high-speed communication with our clients and also with our internal people.

How can technical writers make a transition to a content strategist role?

I think before technical writers can make such a transition there really needs to be the recognition in the organization that such a role is even necessary. The biggest problem in organizations is not one that the technical writer cannot do this role, but certainly organizations don’t see the role as necessary, or that content even deserves a strategy. So a lot of it is really just old ideas that documentation is not recognized as being a valuable asset that requires a proper management strategy, so that’s the primary obstacle.

Let’s say you’ve overcome the problem and your organization has recognized the need for a strategic role. What it means to a writer and a content strategist is that the first thing you have to do is divorce yourself from implementation because technical writers tend to get very caught up in technology, it is just their nature. As soon as you get caught up in the technology, with a mechanism by which a strategy can be implemented, you’re already thinking about tactics and not strategy.

To give you an example, we get lots of RFPs to respond to and I would say 80-90% of these are of these are written in a way that you have to just tick the technical boxes. Very rarely do we see an IT compass, where they say ‘here is a bunch of business problems that we have and how do you solve business problems?’. That is a really important distinction because you start to understand what the real business problem is and what the business outcomes you need are. Rather than ‘do I have this particular tag support of this particular XML schema?’. And even XML itself is an implementation, it’s not what you base your strategy around. And if you read some of Ann Rockley’s materials, she has a great book on content strategy and that book is called Managing Enterprise Content-A Unified Content Strategy. If you read the book carefully you will realize she rarely discusses technology in it. She talks about your information, as information modeling. The tool itself comes at the end. If you want a transition to the strategy role, first get recognition with the organization. That is important. Secondly be able to divorce yourself from the technology in order to think about the actual problems in a strategic way and not in a tactical way.

Could you share any interesting experience from technical writers using Author-it?

There are a few interesting experiences. We have a large number of clients, probably about three and half thousand clients and so I have heard many stories and some of them really need to be mentioned.

HP’s documentation implementation. The success of HP’s implementation, while I’d like to think Author-IT is the primary reason for the success, I can’t because success there has really been due to the gentleman who has set it up. He thought about it strategically and then took the tool and implemented the documentation system in such a way that they have managed to achieve an extraordinary level of reduced content and that’s the result of him executing a strategy that he had.

One of the really cool things I like is when users take a product and do something entirely new with that, which they would never have seen before. One of the achievements that we made last year was to release an SDK product which is something we have been working for years and it basically enables anyone to come along and create extensions of plug-ins. Over the last six months that it has been out, we are seeing new ways in which people are extending the product for completely new users. It has been really exciting.

We have Philips Consumer Electronics who were producing printed manuals and now produce the output of AIT into a Flash format and that Flash format goes inside the television. So you do not need a manual any more. You just use a remote control to navigate into the TV itself which is a pretty exciting story. We also have a business partner in Europe who has developed a whole bunch of extensions that allow Author-IT to be used for specific documentation around the solvency to market in Europe. The development of extensions that others have made are the stories that excite me the most because they are making the product do something new and innovative that we haven’t necessarily been involved in, which is great.

What are the future trends in technical communication? Will there be any dynamic change in the way product documentation is made accessible to customers?

Yes, this is the subject of a recent presentation I gave in the US, about the future trends in technical communication. In my opinion, I have seen a number of specific trends happening in the past few years and let me summarize it for you quickly.

The key trend that I have seen is moving from a Distributed Authoring to a Centralized Authoring environment. What that means is if you took a snapshot of most organizations today, authoring is distributed across many departments and is done using many different tools today. Marketing may use it for design and some web content management. The publications team uses a variety of tools like Word or other tools available in the market. So the trend we see is that the companies want to move from this solo distributed model to a completely centralized model using a single authoring platform to create content, rather than multiple authoring tools creating content as we do it today. This centralized platform will push content to various output formats like PDF, or help systems, or whatever is required.

Moving away from locally installed assistance to online assistance like a lot of the web-based applications. People are not distributing the Help files along with the product anymore and they are publishing it online. The advantage is you can access it quickly and data can be updated easily. In the old method, the update would happen only with every release cycle and it was a costly affair, but always-online format encourages self support and platform independence rather than being specific to a particular format. Above all, online content being tailored to a specific audience/platform/model is one of the most exciting features being developed now.

Moving away from self-hosted knowledge bases or websites by the customers themselves to the advent of cloud technology. This makes the provisioning of our systems to the clients much easier. This means if you want to implement/extend a knowledge base or customer portal for your clients, you would not need someone to do all that stuff and put on a web server. Getting provisions and permissions from IT is a big problem. So cloud technology helps you in self provisioning without the help of IT and running the dynamic knowledge base is safe and updated in minutes. It provides real-time scalability and anytime-anywhere accessibility.

Another trend is moving from Static to Dynamic content. Typically, most content delivered with software or any other product is static in nature and most help systems being shipped are self-static. By self-static, I mean it does not change and is same for everyone and there is no customization done for a particular audience. Whereas in a dynamic content, it gives you the intelligence to change content specific to your audience and changes are reflected in all places. Dynamic content is a big change, enabling much faster access and handling major release changes easily.

The last trend I’d like to mention is closed contribution which is the typical way of creating the content, with 10 to 12 people creating the content. The technical writing groups (a community based approach) are pretty much the only source of content. Now with wikis popping up all over the place, safeguarding content becomes a challenge. With this challenge in mind we are working to protect the community approach of content creation with safe measures and controls put in place for community contribution. In some industries like Healthcare, you cannot have someone come and change the content of presentations or articles. The users of these products are the best experts and add value to the content. Mark Saltz has done a lot of work in the safe community approach.

Compiled by an STC India volunteer

Possibly related articles:

1. Experts Ignite
2. Experts Ignite
3. Experts Ignite

Vol XIII, Issue 1

It’s a new year and we are extremely pleased to bring you the first edition of Indus for 2011. A new year is about beginnings and resolutions for most of us. We look forward to growing, learning and progressing in some way in our lives and careers. We hope Indus helps you on the way in some of these aspects.

A new series Experts Ignite brings you vision and information from experts who are in the forefront of their fields. This edition features Scott Weiss on user experience design.

Sandhya and Gopal introduce us to Translation and Localization as a related and alternate career path for technical writers.

Irma Humby shares her perspective and learnings from managing cross cultural and distance-located documentation teams.

How to grab your reader under sixty seconds is discussed by Anindita Basu.

Expanding your knowledge on RoboHelp and mastering the tool is detailed by Nandini and Samartha.

Bindu Nayar’s article talks about the process of adopting the Wideband Delphi method for estimating documentation effort.

Catch STC news, events, and announcements for 2011 here.

The message from the STC India Chapter President, Rajdeep Gupta, is here.

We hope you enjoy this edition and show your support to the newly constituted STC India Chapter team, newsletter team and all representatives, who have worked hard to start 2011 on a bright note for this chapter!

- Anupama Gummaraju and Sreeraj Nair

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

Possibly related articles:

1. July – August 2011 Newsletter
2. Mar-Apr 2011 Newsletter
3. May – June 2011 Newsletter

I am honored to have been elected to serve as your new President of the India Chapter  of STC.  I am taking over as President from Michelle Cherian who has served in this capacity last year. A special thanks goes out to the previous administrative council and the volunteers for their  outstanding services on behalf of STC in 2010.

We have started chapter activities for 2011 in most of the cities. By the time you read this message, we will have  organized a UX session on Accessibility, a  one-day workshop on Writing and Editing,  a Strategy Games Workshop, among other events. The STC India Chapter also celebrates this year as the year of collaboration in technical  writing and is working with fellow non-profit groups to foster technical communication in diverse areas.

Meet the STC India Chapter officers and volunteers for 2011. Click here to get the full list.

Results from a survey we conducted end of late year tells us that Chennai is the chosen location for our 13th STC India Annual Conference, and we are counting on you to make it a success. We have a huge group  of extremely enthusiastic volunteers and I  am sure we are going to be able to host a wonderful conference this year.

We are still fighting to bring down the membership fees with small wins at present, and hope to bring it down further in the future. Meanwhile, we will continue to keep the STC India Conferences and sessions free for our STC India members and volunteers. Others can attend these sessions by paying a minimal amount.

We are pleased to introduce WebEx sessions to our non-local attendees for  sessions and workshops. This encourages writers from host cities to attend in person as well as to attend the sessions virtually. All this has been possible due to Technowrites who has allowed the STC  India Chapter to use their facility for the  sessions. A couple of cities have already  used this service and the feedback is that  it should spread across every city so  that more people can participate.

We are organizing our first STC India Summit on the  May 7-8 at the Chancery Pavilion, Bangalore.  Given the quality of our conference proceedings, I have full confidence that this Summit will be rich in terms of knowledge sharing and will be a success. The theme of the event  is “Collaboration and reaching beyond your  profession –  How STC India can Empower  your Knowledge & Drive Technical  Communication”. The purpose behind this Summit is the following:

• Develop and distribute more conference proceedings to Indian  technical communicators apart from our regular annual conferences.
• Partner with various non-profit and voluntary groups aimed at spreading technical communication in the world.
• Collaborate and promote Indian technical writers in a global platform.
• Provide companies with a forum to exhibit  their products in Bangalore.

Lastly, I congratulate the previous INDUS team  for their excellent work with Indus and am  sure that the new team will continue the  good work.

- Rajdeep Gupta

Rajdeep is the President and Sponsorship Manager for the STC India Chapter. You can write to him at president@stc-india.org.

Possibly related articles:

1. Prez Talk
2. Prez Talk
3. [Feb-2010] Prez Talk

• STC’s Community Pacesetter Award recognizes innovative and successful community initiatives. Share your innovative community initiatives with the STC world! The deadline for applications is 21 March 2011.
• At the Sacramento Summit, Beyond the Bleeding Edge presents summaries of technologies and methodologies that are too new or unusual to make it into traditional Summit sessions. If you enjoy new technologies or methodologies and like to discuss them, send your proposals to Neil Perlin, by 18 March 2011.
• Every candidate running for the STC office has submitted a biography and answered a set of questions. Ask the Candidate button on STC election website helps you to get to know them even better.
• The highest honorary ranks awarded by the Society are Fellow and Associate Fellow. Here is the list of the outstanding members who will be recognized at the STC Summit in Sacramento this year as Fellows and Associate Fellows.
• The brand new website STC.org went live on 9 Feb! The new site is a huge leap forward from our previous site, and a strong first step toward bringing members the value they expect from STC. Read more about it here.
• CEO and founder of O’Reilly Media and a STC Honorary Fellow, Tim O’Reilly, is the Keynote Speaker at the 2011 Summit! Hillary Hart says, “Tim’s appearance at the Summit recognizes the value technical communicators bring to ’spreading the knowledge of innovators.’” Here are the details of the event. Read more news on the Summit blog.
• Today, 28 Feb, is the last date to renew your STC membership, so that you are able to vote for the 2011 elections. Renew it here.
• Whether you’re looking for a one-hour webinar or a longer, more in-depth certificate course, STC has an increasing variety of online education for you. With new Thursday dates available, STC is offering nine webinars throughout the month of March. See the full listing of webinars to decide which one is right for you.

Possibly related articles:

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

The Instructional Designers Community of India (IDCI), whose mission is to foster community building, training and learning for instructional designers has joined hands with the STC India Chapter. The collaboration will allow for streamlined and regular learning sessions.

IDCI will plan, identify topics, speakers and arrange learning sessions and workshops on instructional design. STC India will assist IDCI with the venue for the sessions and workshops, setting up the workshop infrastructure and the WebEx sessions. The collaboration will come into effect from March 2011. The learning sessions will be held at Novell, Bangalore.

STC India User Research and Usability SIG sessions

The User research and Usability SIG conducted two sessions in January 2011.  Business Impact of Accessibility by Srinivasu Chakravarthula, from Yahoo! and Out-of-the-Box Experience (Designing for First-time Use) by Amit Patil from IBM.

The Business Impact of Accessibility session focused on the misconceptions about accessibility and the low priority it is accorded in the SDLC. It discussed the negative impact of ignoring accessibility and the positive impact on a business if addressed right.

The Out-of-the-Box Experience (Designing for First-time Use) session discussed how first-time user experience stays as the major differentiator for product adoption and acceptance.

The fact that the sessions can be attended via WebEx has enabled more professionals access and participate in the learning sessions, increasing the reach of the training programs.

The sessions were sponsored by Continuous Computing, on whose premises the training sessions were conducted  and Technowrites, who enabled the WebEx session.

STC Hyderabad Learning Session on Freelancing Survival Kit

The first learning session in Hyderabad for 2011 was organized by the STC Hyderabad representative on February 26, 2011. The session was Freelancing Survival Kit anchored by Ravikumar,  a technical writer with close to eight years of experience, currently works with Progress Software, Hyderabad as a Principal Technical Writer.

The presentation provided a hands on guide to all aspects of running an independent freelancing business from scratch. It also covered building and honing skills to showcase your expertise in the open marketplace, nuances of client handling and price negotiation and the varied roles that freelancers can assume like becoming retainers for company where they are contracted for a long term relationships.

Progress Software, Hyderabad sponsored the venue.

STC Gurgaon’s Learning Sessions

STC Gurgaon has kicked off the year with a series of sessions in February 2011. Februray 26^th saw three speakers coming together to talk about knowledge management, estimation techniques and creating documentation in multiple formats.

Angelo Mohan, a Senior Specialist on the Capability Development team from Accenture discussed how technical writers can broaden their role by understanding and managing the vast knowledge banks in their organizations.

Makarand Pandit from Technowrites ran through estimation techniques for documentation projects.  Alok Sharma’s topic was how to create documentation in multiple formats from a single source using HTML Doc, Acrobat, and Dyoxygen.

The session was sponsored by Ericsson.

Possibly related articles:

1. STC India News & Notes, March-April 2011
2. STC India News & Notes, May-June 2011
3. [Aug 2010] Learning Sessions

Sandhya Nair and Gopal Dambal

Infosys Technologies Ltd

Understanding Localization

The process of translating a product and its documentation into different languages or adapting a language for a specific country or region is called Localization. It involves product translation, cultural adaptation (for specific countries, regions, or groups) and customization to accommodate for differences in diverse markets. Language localization is not merely a multilingual translation activity, because it involves a comprehensive study of the target culture in order to correctly adapt the product to local needs. For example the usage of the term Electronic Clearance System (ECS) in the Indian banking scenario is predominantly referred to as Automated Clearing House (ACH) in the global markets.

Localization is sometimes referred to by the numeronym “L10N” (as in: “L”, followed by ten more letters, and then “N”). Localization can be done for continents, regions or countries where people speak different languages, or where the same language is spoken: for instance, different dialects of Spanish, with different idioms, are spoken in Colombia than are spoken in Latin America; likewise, word choices and idioms vary among countries where English is the official language (e.g., in the United States, the United Kingdom, Australia and the Philippines).

When it comes to the processes involved in global sales, apart from differences in distance, time, and production processes that extend across countries, etc., there are also inherent intercultural processes and challenges that need to be addressed. Many companies prepare themselves well by taking up localization infrastructure audits, instituting procedures for production, development, marketing and management. It is therefore surprising that the cultural challenge is pushed aside. After all, the products will be used by people in the target countries. Yet it is difficult to find any references to market culture aside from generic marketing processes. Considering that the product is packaged in words, be it software, an application, a user interface, a website, marketing collateral or a user guide, localization plays a pivotal role in the ability to sell the product, and in the ability to obtain a return on the investment.

Localization is a complex process requiring the use of computer-aided translation (CAT) tools that streamline the work process, improve translation memory, provide consistency and quality, and provide major cost savings. It is a structured process that is easy to manage and run with professional partners. The financial investment aside, localization is highly relevant to and vital for small and medium businesses and startups, to ensure that the original concept envisioned by the product company is also well received by users in different markets as a matter of course.

Elements of Localization

Localization requires an in-depth understanding of the technical and functional domain, language, culture and other parameters that are specific to a region. For example, banking practices and the usage of banking terminologies in Middle Eastern countries vary from that of South East Asia. Such a complex and critical domain not only requires functional and technical knowledge, but also knowledge of legal, regulatory and other banking practices. As the scope is endless for all languages world over, most product companies take the route of hiring consultants for their Localization requirements.

As illustrated, the Localization environment is a potpourri of talent coming from different backgrounds, education and experience. However, content design, organization and management are the prime requisites to efficiently handle Translation or Localization services. This requires people with varied skill sets such as:

• Business communication
• Domain knowledge
• Project management
• Quality control
• Eye for detail (editing)
• Soft skills

Often, the Localization industry requires interaction with people all over the world, depending on the target language. There is the excitement and exposure to interact with people from different regions and backgrounds.

Value add from Technical Writers

A technical writer enhances the understanding of a product or service to an intended audience. Translation and Localization, like technical writing, is all about effective communication. Localization is an extension of technical writing – encompassing other elements like social, cultural and regional parameters.

Possessing strong skills in the basics of effective communication make technical writers the preferred candidates for the localization industry. Their ability to write or translate without losing the context adds significant value to products or services. Some of the key traits that technical writers bring with them are:

•  Inclination to communicate:

Technical writers have an intrinsic aptitude to communicate in an easy to understand style. Effortless and user centric communication through various channels gives technical writers an edge over other professionals.

• Understanding audience:

Audience analysis is the base on which a technical writer builds content. Localization requires an in depth understanding of varied audiences and can be quickly appreciated and understood by a seasoned technical writer.

• Techno-linguistic advantage:

This is perhaps the most important area in which a technical writer can contribute. The technical knowledge advantage, powered by intuitive writing capabilities can break the most complex communication barrier between the product and the end user.

•  Project lifecycle know-how:

An experienced technical writer with good exposure to project management and the software development life cycle can immensely contribute to product or service Localization. An end-to-end understanding of the project life cycle coupled with good negotiation skills enables a technical writer to readily identify gaps, risks, improvements and possible remedies.

•  Eye for detail:

Reviewing, proof reading and editing are some of the skills required for examining documentation in different languages for uniformity, consistency and end user acceptability. A technical writer with these skills can appreciate Localization requirements naturally and not as an imposed process.

Growth Prospects

 For some years now, the IT industry has been the primary growth sector for writers, with English as the predominant language. However, various other industries like Automobile, Medicine, Banking, Finance, and Legal, Transport, Logistics, and Entertainment industries have also caught up. Business expansion across the continents has raised the importance of well localized products, especially in non-English speaking countries.

In India, the translation and localization industry is gathering due attention. Though not many companies are working in this segment currently, well known Indian and foreign MNCs working with products have already realized its scope and importance.

Technical writers are equipped with technical and linguistic advantages which are crucial elements of Localization. Proficiency in foreign languages like Spanish, French, German and Japanese can boost the career and growth path of technical writers. Technical writers with a blend of skills like strong communication, domain knowledge, project management and hands-on experience in foreign languages are surely going to be in demand in the near future. The career progression for such talent is also high as they will become responsible for defining the multilingual strategies for companies.

The following websites have been referred to:

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

http://www.answers.com/topic/globalization

http://blog.lionbridge.com/translation-and-localization

About the authors:

Sandhya Nair leads the Multilingual Services team responsible for envisioning and executing state-of-the-art multilingual strategies for Finacle, the universal banking solution developed by Infosys. The team has developed a robust translation infrastructure and innovative translation management practices.

Gopal Dambal is a member of the Multilingual Services team at Finacle. He is responsible for the execution of Translation and Localization activities in the capacity of Content Lead.

Possibly related articles:

1. When Worlds Collide: Understanding How Documentation and Translation Processes Affect Each Other
2. 7 Habits of Highly Effective Technical Communicators
3. Instructional writing is an art

Irma Humby

Documentation Manager

As I sit sipping my latte in the Global Peace Factory café in Frisco, Texas, accessing their free wireless network, I realize how truly amazing the internet is, and how much it has changed the way we live in this place we call Earth.

When I started as a technical writer for a global company in 1981, “global” meant something different. Sure, we had sales, marketing, and support offices around the world, but we never interacted with those other locations on a daily basis. We did not call any of our coworkers in those places (the toll charges were outrageous), we did not know their names. My daily interactions were with engineers, writers, editors, typesetters, and illustrators in my office, down the hall, or in the next cubicle (sometimes at headquarters in another state). My, how things have changed in 30 years!

How Do You Do?

Since 2001, I have had the pleasure of working with many talented writers, engineers, and managers from India. To prepare for working with team members on the other side of the Earth, my company sent me to a class, “Working Globally,” which focused mainly on working with people from India.  The objective of the course was to learn about cultural differences in the workplace—understand the differences, work with a team knowing those differences, and know what is socially and professionally acceptable.

One of the first things I do when I begin working with a team in India is to find a safe, common non-professional topic that everyone can talk about. This “breaks the ice” (is that a North American colloquialism?).  I may ask where they went to school, whether they have children, or whether they have traveled to the United States (I have not traveled to India). When there is a common non-professional chat before “getting down to business,” people feel comfortable and non-threatened.

So, “getting down to business,” what have I learned while working with cross-cultural documentation teams?

What Time Is It?

We all know that a 12-hour (or more) time zone difference makes us all weary. Who stays up late? Who gets up early? The best solution is to alternate. When having regular doc team project meetings (which there should be), and depending on how long the project is, alternate the meetings, so that one team gets up early for the meeting for two weeks and then the following two weeks, the other team gets up early (some like to call this “sharing the pain”).

When a doc team member is part of a larger project team (as is standard for documentation), ensure the project team lead knows there are team members in another country that have time-zone differences.

Access to all the Information

When the documentation team includes remote workers, make sure all members of the team have access to email aliases, wiki pages for project/product information, applicable specifications; invite them to all project meetings, and if they cannot attend, make sure they get meeting minutes. Highlight areas in the meeting minutes that may affect documentation (schedule changes, team changes, project changes). Sometimes projects are highly confidential and not everyone on the team can get automatic access to information. If this is the case, let the project manager know that your documentation team members need access to all information that should be documented in the product documentation. Find out when the project kicks off, so that when your team meetings begin, all access has been granted.

Kick Off!

When a project is developed and managed in multiple locations, planning and execution are key to the project’s success. When the doc team has remote members, a kick off is one of the most effective ways to get everyone started and on the “same page.”

A kick-off presentation (the kick off is one hour, so less than 15 slides) should contain the following important items:

• New and enhanced features in the project release
• Schedules (alpha, Early Field Trial (EFT), First Customer Shipment (FCS), the schedules that apply to your organization
• Key team members (product manager, program manager, engineering manager, alpha/EFT manager)
• Affected docs/doc strategy
• Links (URLs) to important project information (specs, project wiki, email alias)
• Access to the project doc wiki and email alias
• Doc team status meeting schedule
• Doc plan location or doc wiki
• Writer assignments

Keep on Track

After the kick off, hold weekly doc status meetings; if applicable, record the meeting. Send the agenda to the team one or two days before the meeting, and ask the team to send agenda topics. Send the final agenda a few hours (sometimes it could be the previous day) before the meeting. Include the following topics in the weekly meetings:

• Milestones (doc reviews, building books, EFT, FCS); track how the doc team is progressing
• Issues that writers encounter (getting information, contacting SMEs, not enough bandwidth); include action plans to mitigate project risks
• Changes in the project (doc team leads should attend the weekly project status meetings and share the information in the doc project meeting). Changes might include schedule updates, added features, removed features, project issues with schedules, development delays
• Assignment updates
• Track previous and current defects and update the docs for the upcoming release (hint: publish on wiki and include the assigned writer)

Release!

The final weeks before the project release (first customer ship-FCS) are the most stressful and meeting milestones are crucial to the success of the project. On the doc wiki or in the doc plan, closely track the following FCS deliverables:

• Build and check in final online help
• Build final documentation
• Print applicable documents
• Complete release notes
• Publish docs to customer-facing locations
• Notify project team when final documentation is available
• Prepare for localization

Communicating with team members on a regular basis, sharing information, and overcoming obstacles are the keys to a successful project release. Keep the “global” door open at all times. Do not forget to celebrate!

About the author

Irma Humby has won multiple awards from the Society of Technical Communication during her 30-year career as a writer, editor, project manager, team lead, and manager for technical documentation. Irma has worked on cross-cultural teams located in India, Canada, China, Australia, and multiple European countries. Irma works for a multi-billion dollar global company of unified communications in Dallas, Texas, where she resides with her husband and two of her three children.

Possibly related articles:

1. Requirements Gathering for Agile
2. Developing documentation for agile
3. Publish-As-You-Write Model for Documentation

Anindita Basu

Sixty seconds is what Nicolas Cage got to steal a car. You get less than 60 seconds to steal the attention of your readers and get them on to your help page. The first 10 words on any page take less than 10 seconds to read and understand, and those words are the ones that tell the readers if that page contains the information they are looking for. This is the reason why opening lines are so important – they are hooks that pull readers on to your help page, especially if the readers are looking at the results of a search and trying to decide whether to click through.

In this article, I list four tips for writing introductory paragraphs. For the first three tips, I give two versions of an example and leave you to decide which is the better version.

Tip 1: Do not repeat the title

Repetition takes up real estate. In a search result, the topics are listed by their titles followed by at least 50 words of the first sentence. The introductory paragraph should state something that is not already evident from the title itself.

Tip 2: Do not begin with expletives

Expletives are ‘padding’ that are best avoided when you are trying to fit in the entire crux of a topic into only 50 words. Rephrase the sentence to weed out words such as “This topic contains…”, “There are four different…”, “It is important that…” and get straight to the point. You can elaborate to your heart’s content from the second paragraph onwards, but use the most important words first in the first sentence of the first paragraph.

Tip 3: Give a snapshot of what the topic contains

Think about what you are writing. Are you explaining a concept? If yes, define the main point of the concept. Are you describing a procedure? If yes, state why the task should be done — the purpose and the benefit. Are you providing some reference information? If yes, describe what kind of information the topic contains. In other words, make the introduction relevant for the readers — tell them why they should read the topic.

Tip 4: Write the introduction after you’ve written the topic

Do begin your writing with an introductory paragraph by all means. But after you’ve written the entire section, go back to the beginning and see if you have captured the essence of what you’ve just written in those first three lines of that topic. This is something that I follow; your mileage may vary.

End Note: If you are writing with DITA, never ever omit the <shortdesc> tag. These tips specifically target the <shortdesc> tag but they hold good for all introductory paragraphs.

That’s all I have to say today because I wanted this to be a very short write-up. Now, over to you – do write in with your tips

About the author

Anindita Basu is a writer and editor with IBM, India. She blogs and tweets about technical writing; sometimes, she also tweets on random subjects.

No related articles.

In a new series called Experts Ignite, Indus brings you experts in the field of technical writing and related industries who bring new perspectives to our careers and share their experiences. In this first edition Indus presents Scott Weiss, Director of User Experience at Misys, on the user experience (UX) design industry and insights into how technical writers can evolve into UX practitioners or evangelists. He also talks about the prevalence and importance of user experience.

How did you start your career in the user-experience industry, and how has your journey been?

I started as an intern at Apple Computer in 1989, working on Macintosh System 7. After I finished my degree I went to Microsoft, where I was the program manager for Schedule+ for Macintosh, which we know today as Outlook. At Microsoft I also worked in Advanced Windows Services on the product that became Windows 95. I worked at Sybase and Autodesk too, and then started a user experience (UX) agency in New York City that I ran for 11 years. While I was doing that, I wrote “Handheld Usability,” which re-focused my career in mobile usability. Now I’m at Misys, working on financial software, which is the new golden field of opportunity in UX. Banking has so many complex challenges, bringing us a great chance to grow and to see tangible changes in a short time.

How can technical writers evangelize the importance of usability in their organization?

UX professionals tend to find fault in things—that’s what we do. It’s easy to be disliked and avoided with that kind of approach, so it’s better to come up with ways to improve things and to demonstrate it to team members than to criticize their work. Create a new design, make it look nice, and share it. When people see how great it is, they are likely to ask how you did it, which is when the time is right to talk about UX and its benefits. Making graphical posters about target users and putting them up around the office helps a lot. Also, identify UX standards and upload them up to the company intranet, demonstrating how they can help save developers time and reduce customer training time too. Be proactive and helpful—people will notice.

Can you share some tips on how technical writers can prepare a portfolio when they have limited or no experience in the usability industry?

The most important thing is to have a portfolio of work. If someone wants to learn about design, then he or she should start designing. Make a game, or a site, or a blog that demonstrates your ability. Instead of critiquing, re-design. If you don’t like the way your phone works, document it, redesign it, and blog about it. A while back I presented at a World Usability Day event in London about how terrible the Transport For London mobile journey planner was. People were really mad, since everyone loves TFL. Afterward, I spent a lot of time re-designing the mobile solution and then published the designs. People were much more interested in my design work than my critique.

What are the skills that you look for while hiring a UX professional?

The portfolio of work is most important, as well as a positive attitude and great communication skills. So much of what we do is working with people, so really good inter-personal skills are critical.

What are the different types of interfaces where user experience plays or is expected to play a prominent role?

UX is now everywhere. From the controls on a washing machine, to the new internet-enabled televisions, complex user interactions are a part of our everyday lives. One of my college projects was designing the UI for an automobile air conditioning system. And what about the settings on a refrigerator, or household programmable thermostat? Just about everywhere you look, there are user interfaces and UX considerations.

For a UX design or redesign project, what are the main parameters that a company looks at for ROI?

The classics: reducing developer time, reducing customer training time. Reducing customer support call duration and frequency too. It’s all about saving money for ROI.

Scott is presently the Director of User Experience at Misys. He has held the position of Executive Director, HFI, London. His expertise includes Usability, Information Architecture, and Market Research with a specialization in mobile usability. Scott is known world-wide for his leadership in mobile usability design, prototyping, and user testing. He is a seasoned market research and information design professional with significant management experience as well. He is the author of “Handheld Usability” (Wiley: 2002).

Compiled by an STC India volunteer

Possibly related articles:

1. Experts Ignite
2. Experts Ignite
3. Experts Ignite – Paul Trotter, Author-it

Bindu Nayar

Do you feel that estimating the documentation effort required for a project is nothing short of predicting the future? This view is strengthened when the estimates are inaccurate and the project is plagued with variance in scope and delays in delivery.

Any project is controlled by four major variables: schedule, scope, resources and risks. Unexpected changes to any of these variables can have an unexpected impact on the project. Therefore, it is imperative to make a “good” estimate of the time and resources required for the successful delivery of the project. The key is to not underestimate or overestimate the effort required.

There are many well established methods for effort estimation. Before you decide to adopt a particular method, it is important to understand whether the estimation method fits your needs.

Through this article, I will share my experiences in using the Wideband Delphi method of estimation for documentation projects. The process outlined in this article is customized to real-world project needs and the documentation life cycle.

What is Wideband Delphi?

The Wideband Delphi method evolved from the Rand Corporation in the 1940’s as an estimation technique. In the 1970’s, this method was re-evolved to include greater communication, interaction and participation among the estimators. The method, which was earlier used as an estimation tool in the sales and marketing field, was later on used for estimation in software projects.

Let’s take a look at the process.

Prerequisites

You need the following information before you begin the estimation process:

• A list of features or the Product Requirements Document (PRD) that will have an impact on your product.
• Milestones and deadlines for the release of the product.
• List of subject matter experts (SMEs) who can help you understand the changes better.

The Process

The Wideband Delphi estimation technique involves the following steps:

• Identifying the estimation teams
• Introduction/kickoff meeting
• Preparation
• Estimation meeting
• Closure meeting

Identifying the Estimation Teams

An ideal estimation team comprises 3-7 members. Usually, the project manager decides the team composition and appoints the moderator. In the absence of a project manager, the author can take the responsibility of deciding the team members.

The estimation meeting must include key SMEs, the engineering manager, and a peer. This composition ensures that all aspects of documentation and the project are factored in during the estimation meeting.

Introduction/Kickoff Meeting

In this meeting, the author shares the scope of changes that will affect the documentation with the estimators. This information helps the estimators to get acquainted with the product changes that have an impact on documentation. The author should share only the scope and the impact on the documentation piece and not the effort involved in getting the work done.  This step is important to ensure that the estimates worked out are fair and without bias.

Illustration 1: Scope of documentation changes

While sharing the understanding of the features with the estimators, make sure that you share the authoring process as well. For instance, if you need to conduct peer reviews, technical reviews, and unit testing to consider a feature as complete, share this data with the estimators.

Sharing the scope and impact on the documentation helps set the context among the estimators. This ensures that when all the estimators meet for the next step— the estimation meeting—everyone has the context. This will help effective utilization of time.

Preparation

After the author shares the scope and impact, each estimator individually generates the initial estimates for each change. During this process, each estimator also assesses the scope and impact details shared by the author. The data from this activity is intended to be utilized in the estimation meeting.

Estimation Meeting

At the start of the meeting, the moderator or the project manager charts down the estimators names and the list of features for discussion. In the estimation meeting, the moderator leads the estimation team through iterative steps to get a consensus on the estimates.

The moderator then asks each participant to share the estimates. All the estimators have the details ready after the Preparation phase. As illustrated in Illustration 2, all estimators start by first sharing the size estimate in pages and then the effort estimates in terms of person days.

In a typical scenario, the authoring process involves more than just writing about the product. It also involves a series of steps ranging from understanding the feature to unit testing the feature to ensure correctness and completeness.

In this case, the author’s effort estimate indicates the effort spent by the author in getting the document ready for review and incorporating the comments from the reviewers. During the estimation process, the other estimators are also called upon to assess how much time they think the author should ideally take to author and review the document.

Illustration 3: Author’s estimates

Let us use an example to make this point clear:

Author A needs to document five new features for a release. The author has made estimates on what is the size of documentation and the effort required to get it done. This is what the author’s estimates look like:

The other estimators also share their estimates. In the above figure, you can observe a variance in the estimates of the estimators. This is expected because every person has a different perspective on the effort required to complete a work product. The Wideband Delphi method is devised to deal with such situations and arrive at a consensus. It is now the turn of the moderator to assess the variations and investigate why the estimates differ and if there is a way that the estimates can be revised.

In Illustration 4, look at the effort estimate data corresponding to Feature 1. All the estimators agree on the number of pages that Feature 1 will require, but they don’t agree on the effort that is required.

It is now up to the moderator to find the reasons for the variance. He or she asks each estimator to explain the assumptions behind the estimate that they have suggested. If required, the author can explain the scope again and the impact of scope on documentation that was considered while projecting the effort. The other estimators then re-assess their estimates in the light of the explanation and can revise the estimates.

This process continues until all the estimators arrive at a consensus. In some cases, the estimators may not arrive at the same effort estimate even after multiple iterations. So the Wideband Delphi method allows for a variance of .5-1 person days or a variance of .5-1 pages. However, if there is a higher variance, the moderator must help the author to revise the estimates.

While estimating effort for complex projects, it is recommended to gauge the effort estimates using principles of “best’, “worst”, and “likely.” Here “best” indicates a scenario where there is no uncertainty about the scope and impact. “Worst” indicates a scenario where there is very high level of uncertainty. A “likely” scenario is that in which there is a medium level of uncertainty.

After all the estimates are listed, the moderator arrives at a nominal value by averaging out the variance. The nominal value is the best indicator of effort that will be required to complete a feature.

As explained earlier, the estimation team can do multiple iterations to iron out the variance and agree on the effort and size of the deliverables.

Closure Meeting

The closure meeting is the last step and is often not mandatory. This meeting usually takes place if, despite repeated iterations, the estimators cannot arrive at a consensus. In this meeting, the author clarifies his or her stand on the estimates and explains the reasons for the projected estimates. The last word on the effort estimate lies with the author.

Delphi in the Real World

No projects are static in nature. In a real-world scenario, many factors can impact the scope of a project. Every time the project faces a variance, it is important that you reassess the assumptions and conclusions and make adjustments accordingly. Using the Wideband Delphi method of estimation has several advantages over other methods of estimation for the following reasons:

• The introduction meeting helps build a complete task list or work breakdown structure that can be utilized for other major documentation activities.
• As the base of this method is arriving at a consensus, it helps to eliminate bias in estimates.
• No estimator knows what the accurate effort and size is, for a deliverable. Therefore, there are no right estimates or wrong estimates but just realistic estimates. A mix of stakeholders ensures there is no bias in the estimation process.
• This method depends on iterations to arrive at effort and size estimates and thus re-establishes the value of iterations to complete a complex activity.

About the author

Bindu Nayar is a Lead Technical Writer with over 10 years experience in the technical writing field with core experience in protocol and developer documentation. In addition to primary role of authoring, she is currently involved in project management activities at Novell.

Possibly related articles:

1. RCO, Estimation, & Ratio Analysis Technical Documentation, Part 3
2. Applying Lean Six-Sigma Principles to Documentation
3. RCO, Estimation, & Ratio Analysis Technical Documentation, Part 1

Nandini Gupta and Samartha Vashishtha

If you’re a new or intermediate-level user of RoboHelp HTML, you’ll surely find this compendium of 24 commonly encountered terms useful. And once you’re done with the basics, go ahead and explore the community content links under the respective term.

Note: Some features discussed in this article are not available in RoboHelp HTML version earlier than RoboHelp 9.

About the authors

The authors work on the Community Help and Learning team at Adobe Systems. You can follow them on Twitter at @nandinizg and @samarthav.

Possibly related articles:

1. Five RoboHelp tips

VolXII, Issue 6

In this last issue of 2010, we bring you a magazine with some reflections and some recollections. Some writers chose to write about their experience at the STC Conference, some other penned their thoughts on the tech writing community itself. What is it that defines us? Makes us what we are? What is it that we look forward to? What is it that we must prepare ourselves for?

Yes, the end of the year is a good time to take stock of all these questions.

I hope each and everyone of you, dear readers, grew a little, learnt something this past year. I hope you tried something new – be it a tool, or a process, or even a technique. I hope you succeeded in some endeavors. For the left-over goals, there is still tomorrow. There is 2011.

Happy new year readers, and hope the coming year is fulfilling and enriching for all of you.

In this issue, Rufus presents his vision of the future for Indian technical writers.

Tabir breaks down the economics behind the hiring process. Check it out for an insider’s view.

The A-Z of technical writers, brought to you by Anindita – funny and bang on target!

Rachel tells us why Naresh Gupta’s keynote speech at the STC India Annual Conference made an  impact.

Pranav aka Joe Sponge gives us his first-impressions of STC and the STC India Annual Conference.

Of course we have the third and final installment of Makarand’s study.

Don’t miss the  STC announcements, STC India announcements, the STC India learning sessions and the year-end-special list of STC India volunteers.

As always the STC India chapter President, Michelle Cherian, has a message for you.

- Anagha Chandratrey,

On behalf of the INDUS team.

Possibly related articles:

1. Sep-Oct 2010 Newsletter
2. July-August 2010 Newsletter
3. Jan-Feb 2010 Newsletter

Re-enabling the Indian IT workforce

– P. Rufus

In the early 1990’s, when the US began outsourcing technical writing to India, a few American technical writers forecast that such ‘raw documentation’ done ‘cheaply in India’ would get back to the US for the final finish. Somehow, that didn’t happen in the envisaged scale. Eventually, many American technical writers lost their jobs.

MISSED WISDOM

To meet this trend, a leading technical communicator in the US suggested that American technical writers should introspect on their innate talents and evolve their roles with the emerging business scenario. (Of course, job change was an easy option.) The suggestion was interesting, as it  pointed to roles that would become integral to policy, strategy, analysis, marketing and innovation that businesses won’t outsource. I am not sure how many heeded that advice and looked beyond traditional technical writing.

Today, I think the wisdom in that advice is relevant for a role which Indian technical communicators can play towards retaining India’s advantage as a prime outsourcing destination. This role transcends ‘writing documentation’ in its most inclusive sense. It involves re-enabling the Indian IT workforce in communicating their ideas, solutions and services effectively in English. So that global business would increasingly look to India for superior solutions and engagement experience, rather than for discount pricing.

BEYOND THE SUNSHINE

For the last two decades, Indian technical communicators have flourished.  In TCS, global clients have paid good price for special technical communication solutions. TCS also develops patent innovations for high-end technical communication solutions, and has offerings that provide competitive differentiation that helps win large value, strategically important software projects! There are also companies and freelancers who exclusively offer technical writing services in India.  So, we are well established.

Yet, some US lessons from the 1990’s and our growth there from, may be relevant, given what is forecast for Indian IT and our heavy dependence on it. The reasons lie in China and Macaulay’s India.

MACAULAY AND THE DRAGON

We owe our forte in the English language to Lord Macaulay (1800-1859), deputed from England in 1834 to proliferate English in India. His intent was to make Indians ‘a better people, knowing English’ and perhaps worthy subjects of Her Majesty. I am sure he would be delighted at us also using the ‘English advantage’ in exporting information development services and solutions.

English will remain the lingua franca of world business for many years. China has been watching India’s English advantage, while India has been vainglorious. A 2000-01 census estimated that about 10.7 per cent of Indians could speak some English. In absolute number, it was next only to the US. This key differentiator made India the preferred destination for outsourcing software and IT services, especially from the US and UK.

A British Council study report titled ‘English Next India’ (November 2009), observed that India could be trailing behind China in terms of the total number of English speakers (not considering fluency). China has been enhancing its educational policies, adopting modern pedagogy, sourcing specialist faculty from abroad and above all, targeting English especially at its younger population. Estimates indicate that China could be adding about 20 million English speakers to its workforce each year.  This growing advantage is also complemented by tax exemptions to Chinese companies that would enable them to offer lucrative pricing for outsourced work.

ENGLISH, NEXT INDIA?

India is watching all this and I hope we technical communicators are too. Our English advantage has been waning. Today, we cannot understand what some of our software developers say, write or develop in English—email, presentations, documentation, meetings and software. Indian vernacular dialects of poor English are also gaining strength from campus to business. Eventually, will the global IT market have to choose between this Indian variety and just one Mandarin English?

But the good news is that Indians are realising their growing deficiency in English. To such extent that Dalits have built a temple in Banka village (UP) to ‘Goddess English’, all timed for inauguration on the birth anniversary of Lord Macaulay this year. Hopefully, their devout pujas (and diligence in learning English) will make the Goddess smile on all Indian academia, especially schools and engineering colleges.

THE DRAGON, ELEPHANT AND TECHNICAL COMMUNICATORS

But then, good English is not an instant boon. The concern is whether the agile Chinese dragon will outpace the Indian elephant, by the time the Indian IT workforce can communicate effectively in English. It is here that Indian technical communicators have a role to play. It involves both remedying the English language ability of the Indian IT workforce and complementing it with basics in technical communication. All this must be imparted through training, processes, assets, value-adding reviews and edits and focused guidance in authoring. Simply because, for every technical communicator, there are several software developers, who engage with the world. Therefore, the technical communicator’s role must essentially be catalytic, expansive and vocational.

However, the role is not easy, as I have realized in my three decades of experience as a technical communicator. It is easier for a technical communicator with domain knowledge to write good technical documents. But helping someone else do it is a challenge. Making someone else write effective business email is an even greater challenge, because it’s not an email problem.

YES, WE CAN!

Unfortunately, the IT industry labels communication competence as ‘soft skills’. These are ‘core skills’. As technical communicators, we can make our software colleagues realize this. Additionally, we can enhance their documentation/communication skills by a calibrated approach that’s sensitive to their project pressures. Such value is high and spreads far. It means not only teaching hungry men how to fish, but also ensuring a larger catch of business.

For several years now, this role, vocational zeal and arduous effort have helped ‘Technical Communication’ rank among the Top 3 Corporate Functions in TCS. A rank voted by software professionals! I am citing TCS merely for it being fairly representative of Indian IT and my personal experience in working with it.

India Next needs this. Indian technical communicators owe this.

About the author:

Rufus heads Technical Communication (TechCom), which he set up as a Corporate Function in TCS.  He primarily envisions the direction for TechCom, builds consultants, innovates patent solutions, manages the overall function, and also writes, reviews and edits.

A TCS veteran of over 25 years, Rufus has built a team of highly talented, process-oriented Technical Communicators who have executed projects for global clients including the Fortune 500. Rufus has led TechCom in a pioneering, dual role in both developing a variety of information solutions and building the communication capability of TCS’s IT professionals. The role’s value-spread has resulted in TCS professionals voting TechCom to the league of Top 3 Corporate Functions in the company successively for several years now.

Early in his career, Rufus worked in a product development project at an IBM Lab in the USA. He is a Graduate in Chemistry, University of Mumbai, and holds a Diplome de Langue from Alliance Francaise de Paris.

Rufus can be reached at p.rufus@tcs.com.

Possibly related articles:

1. 7 Habits of Highly Effective Technical Communicators
2. Technical Communicators as Heuristics Reviewers
3. Technical Writing to Localization – An Emerging Career Path

– Tabir Mishra

“Hi Everybody,

I have an interview to attend for Technical Writer position, I am technically fresher in this field. Can anybody guide me, what type of questions are asked … ”

“Hi,

I want to know what is the process most of the companies follow to appraise a Technical Writer…”

“I have gone through the course contents offered by various institutes and am not able to decide whether joining a course and obtaining certification really helps. I am one of those people trying to break into technical writing and was planning to attend a course if it was really required. Can anyone clarify this?”

“Hi Everybody,I have an interview to attend for Technical Writer position, I am technically fresher in this field. Can anybody guide me, what type of questions are asked … ”
“Hi, I want to know what is the process most of the companies follow to appraise a Technical Writer…”
“I have gone through the course contents offered by various institutes and am not able to decide whether joining a course and obtaining certification really helps. I am one of those people trying to break into technical writing and was planning to attend a course if it was really required. Can anyone clarify this?”

Questions like these plague the new and the old alike. What does the recruiter look for? Why does the company favor one employee and neglect the other? Why does a manager listen to one employee, but disregard the other? Why do employees get bad performance appraisals? The answer seems to span industries, and some of the issues technical writer faces are also shared by people in other professions.

Before attempting to answer these questions, let’s make a couple of assumptions:

• Assumption 1: The candidate/employee is reasonably good professionally, and does not have any serious personality kinks
• Assumption 2: The manager/recruiter does not have a grudge against a specific employee or candidate
• Assumption 3: The company policies are reasonably employee-friendly, and the company is doing reasonably well in terms of revenue; hence lay-offs are not the order of the day.

THE PROJECT TRAJECTORY

In order to understand the management perspective, it is helpful to first understand the business model of an average company. Companies work to earn a profit. They do this by selling products or services. Each new product or client requirement is treated as a project.

In a product or service-based company, a project would go through the following stages:

Every stage in the project life-cycle involves a cost to the company, in terms of infrastructure, salary, and taxes, which must be recovered from each employee. This is done by ensuring that the employee is productive enough to justify the salary and facilities being given to him, and is also doing enough work to earn the company a profit.

INSIDER’S SECRETS – THE FINANCIAL ANGLE

Final Product Price/Quotation = Project cost + profit markup + taxes.

Taxes (service tax, VAT etc.) go to straight to the Government kitty; the project cost is pure expense. The company benefits from the profit markup.

The project cost is calculated as follows:

1. Development Costs = Salary per day of employees involved * number of days
2. Manpower Costs

A manpower requirement estimate is calculated depending on the project complexity and duration. For example, for a very small project, manpower cost estimates could be calculated as follows:

Employee Profile	Salary per month (Indian Rupees)	Monthly Seat Cost (Indian Rupees)	Work Involvement for productivity
Project lead (existing employee)	45,000/-	20,000	Must oversee and deliver at least 600 pages per month
Tech Writer 1 (3-4 yrs exp)	35,000	20,000	At least 10 new pages/day + language review of 10 pages/day
Tech Writer 2 (1-2 yrs exp)	20,000	20,000	10 new pages per day
Graphic Designer	20,000	20,000	6 diagrams per day
Total	1,20,000	80,000	Total Manpower Cost = Rs. 2,00,000/-

where Monthly Seat Cost per employee= (Office space rent + electricity bill + office maintenance + miscellaneous costs) / number of employees.

3. Marketing and Liaising Costs: Costs incurred by the marketing and liaising team in getting the project sanctioned, liaising at the management level to sort out issues in coordination, advertising and marketing the product.
4. Logistical costs: Travel costs for site visits, cost of support staff such as graphic designers in getting documents ready for the project, cost of software that may need to be procured for the project, product shipping costs.

Each company then decides the percentage markup at which it wants to operate. for example, a company may decide to work on a 10% profit margin. If the only taxes to be paid are service tax @ of 10.3%, the final costing for a project cost of Rs. 50,00,000/- might be

Final cost/Quotation = 50,00,000 + 10.3% + 10% = 60,66,550/-

THE GRADING SYSTEM

A company evaluates each employee in terms of financial return vis-à-vis cost to company.

1. An employee who does not complete his work on time (contributes to project delivery delays), has bad language skills (increases review time and effort), argues with the manager (wastes productive manager man-hours), does not inform well in time before taking leave (brings instability into the project timelines) is considered a bad employee.
2. If an employee earns his salary and also covers his seat costs, he qualifies as an average employee.
3. If he exceeds this figure, he’s good.
4. The exceptional performer exceeds the CTC/output ratio expected by the company manifold.

The grading is awarded based on feedback given by the Project Manger or Team Lead, and also by the amount of work accomplished by the employee per day/week/month during the project. In the ideal scenario, this is just about as impartial as an evaluation process can get.

Based on these parameters, let us now take a look at the hiring process.

Manpower hiring is done on the basis of a Job Description prepared by the Project Manager or someone who has a clear idea of the project requirements. The Job Description tries to give the HR team a visual picture of the perfect candidate. The intelligent candidate guesses the contents of the Job Description, and tries to fit into that perfect picture.

Some sections of a Job Description could be:

1) Perception of duties – exact details of what the new hire is to do once employed, down to the daily schedule to be followed. For example, a content writer’s Job Description could read:

“Conceptualizing, suggesting, and finalizing the template design, selecting images, deciding color schemes and writing content for

- Brochures and flyers

- Client projects (web content, newsletters, magazines etc.)

- Advertisements for online branding campaigns, newspapers, magazines and other media

- SMS’s and promotional emails ”

2) Domain Knowledge – A detailed description of the technical skills expected of the candidate e.g. BE Computers with 2 years of telecom documentation experience

3) Tools – The tools the candidate should be familiar with (optional for freshers)

4) Personality Traits – Depending on the seniority, what is expected out of the candidate in terms of office interaction and responsibilities. e.g. No fixation regarding work timings, Pleasant to speak to, with good client interaction skills

5) Suggested Company Background: What kind of companies should the candidate have worked for? E.g. must have worked as a Technical Writer for a telecommunications company such as Nokia-Seimens Network or Ericsson.

6) Rounds of selection – What should the testing process involve? What kind of questions should be asked? The Manager often prepares a written test to be used by the HR team.

· Round 1: Grammar and spelling check Refer to test sheet 1

· Round 2: Comprehension Refer to test sheet 2

· Round 3: Prepare a User Manual on “Configuring a Windows XP Firewall”

7) Salary – A salary range, depending on the rough experience level available e.g. 17,000 (for 2 years experience) – 22,000 pm (for 3+ years + of experience)

PERFORMANCE PARAMETERS – WHAT DOES THE MANAGEMENT EXPECT?

Let’s try and answer the question specific to the Technical Writing field:

Freshers: For a fresher, the recruiter would probably look at plain grammar, basic writing skills, maybe some IT skills, and good knowledge of MS Office. The project manager is going to use a fresher as (putting it bluntly) cheap labour! Without being offensive, this means that the project lead is going to allocate that part of the project to the newbie that doesn’t require technical skills – maybe preparing PPTs, proofreading or writing very basic descriptions.

To be fair, the project lead is going to give the newbie a chance to learn by interacting with seniors, so that a long-term asset is created for the company. If the fresher has basic knowledge of tools or a certification – good! It’ll speed up the learning process, but the management knows that actual learning will take place on the job. In any case, a good recruiter sets a stringent test, and relies on first-hand feedback before making a decision. (This should take care of questions asked by newbies regarding the need for certifications and knowledge of tools)

THE LINKAGE

Arriving at a loose link between salary or performance with capability, highly-paid and highly-valued employees are those who are capable, and are ready to take on responsibility. Hence, employees who are keen to take initiative and act as solutions rather than another headache for the manager (aren’t the boss and the client enough!), are looked upon as company assets.

Such employees are valued, cultivated and nurtured by an organization. They contribute to the productivity within a project and help the company grow. From the point of view of the management, hiring and training a new employee is a major investment in terms of time and effort. It’s also expensive in terms of resources, because a new hire means time spent on creating a Job Description, tests, time taken in interviews, initial training and alignment – massive involvement of the manager and the HR team. It is far more productive to retain good manpower and treat them well.

About the author:

Tabir Mishra (tabir@conwiz.in) is working as DGM(Projects) at ConWiz, Noida.

About the illustration:

Used with permission from Anagha Chandratrey.

No related articles.

- Anindita Basu, with inputs from Rachna Ganguli and Anagha Chandratrey

• A is for Adobe.  The company that left Anindita with the distinct impression that it thinks that that the techcomm world revolves around it. Also see F and R.
• B is for Beta.  It stands neither for the second letter in the Greek alphabet nor the second brightest star in a constellation. It stands for not-yet-ready releases and is an excellent medium for techcommers to get feedback on their work.
• C is for content. That which makes the techcomm world go round.
• D is for DITA.  That thing which cures all ills.  Sane voices suggest otherwise but people still see through the glass darkly.
• E is for English.  A language much maligned by a tiny, pint-sized apostrophe, which, if misaligned, can even become a comma. E is for editors. That group of people who are haplessly left with correcting the thats and whichs when what they’d dearly like to do is spend time on indexes, navigation, and coherence and cohesion.
• F is for FrameMaker (See A). F is for feedback. A message where the message is often confused with the messenger, often unjustly.
• G is for Google.  It is a help authoring tool that saves a lot of SME time (see S).
• H is for Help. A verb and a noun (See the possibility related V). Help is a privilege. You may want it but not get it.
• I is for information. Information is a noun that cannot stand on its own; it must always be used as an adjective. Information design, information architecture, information developer, and information overload, for instance.
• J is for coffee and pictures. As in, Java and JPEG.
• K is for knowledge.  Of, besides writing, the tools, domains, and processes.
• L is for listening.  It stands for the characteristic of being alert and ready to hear anything that might lead to knowledge (see K).
• M is for multimedia, an umbrella term for anything that moves, creates noise, and can be packaged.
• N is for No. As in, “No, I will not document how it should work; only, how it does indeed work”, “No, I will not put this screenshot here because …”, “No, this will not go into an install guide because….”
• O is for obfuscation.  So long as obfuscation exists, so will a technical communicator.  If you do not know what obfuscation is, here is an example: “The relationship, which I might tentatively venture to aver has not been without a degree of reciprocal utility and even perhaps occasional gratification, is approaching the point of irreversible bifurcation and, to put it briefly, is in the propinquity of its ultimate regrettable termination.”
• P is for PDF.  It was born in 1993. Other births that year include Microsoft Windows NT and the republics of Slovakia and Czech.
• Q is for  curiosity. Why should I…? How does this…? When will it…? If I do this, what will….? What’s the difference between…? What is the weight of the moon?
• R is for RoboHelp (See A). R is for respect. An emotion that causes much existential angst among techcommers.
• S is for scrum. It means giving daily updates to your team and then running back to do the work you yourself promised to. S is for SME.  It means the fount of knowledge from which information must be gleaned. S is for substance (See C). S is for style. It is something best only followed, not tampered with.
• T is for Twitter.  A medium used almost exclusively to pimp blog posts, product launches, and rave reviews. T is for TWIN. Bonded for life.
• U is a letter so important that it must never be used in isolation. U is royalty and must always be teamed with other letters, like this: UX, UA. U is the reason techcommers exist; U is for users.
• V is for vision. That which makes techcommers put descriptions in alt text, pick the reds and greens with care, and prefer lists to tables. The ability to see beyond the obvious, to ‘write’ for everyone.
• W is for wiki.  Everybody knows it’s there but nobody knows what to do with it, hoping that somebody comes up with a wiki-to-source roundtripping that helps anybody adopt a wiki.
• X is a placeholder. As in XML.
• Y.  A letter for which I could not come up with a word. I did try to match it to words such as Yes, Year, Yearn, and Yesterday but felt something was missing.  So, I am leaving Y alone. For You, the reader.
• Z is for zen.  And the art of writing for motorcycle mechanics.

Acknowledgements

• Rachna Singh Ganguli for G = Google, F = feedback, Help is a privilege, J=Java and JPEG, R = respect; T=TWIN.
• Anagha Chandratrey for K = knowledge, L = learning.
• The Beatles, for “Listen! Do you want to know a secret”.
• The people of The Sound of Music (1965) for “Let’s start…with A-B-C” and “When you know…most anything”.
• The people of Yes, Minister (BBC) for “The relationship…termination”.

About the author:

Anindita Basu is an information developer at IBM, India.  She blogs at http://writing-technical.blogspot.com and can be reached at ab.techwriter@gmail.com.

About the illustration:

Used with permission from Anagha Chandratrey.

No related articles.

– Rachel McAlpine

I had an intensely rewarding time at the STC India 12th Annual Conference, on my very first visit to India.  There were many highlights for me. For example, I certainly won’t forget Dr Naresh Gupta’s visionary presentation on the future of content.

We can’t escape the mobile internet. That’s the future, coming ready or not. For my company, training by mobile phone or iPad will be a major development.

One message pleased me: “Globalize and localize”. Very few people realise that their own brand of English is not universally understood. Since living in Switzerland and Japan, I’ve taught global English: it crosses borders and is easy to translate.

Content, Dr Gupta pointed out, must also be modular, accessible, searchable, customized, multi-sensual, collaborative, consumable, interactive, and open to customer input or feedback.

What a list! Writing for work involves so much more than it used to. Clarity and correctness are not enough.

Whatever Dr Gupta predicted about content must be implemented by the people who create content. All those skills and more must be actively learned: they don’t come naturally. Content authors are made, not born.

I train content authors to write for work, and today, that means writing usable, reusable content.  Moreover, content management systems and other technologies demand that people write with meticulous structure, focus, and economy. Soon the mobile internet will change requirements yet again.

For you, a technical communicator, all this may be an interesting challenge—and your writing skills have never been more in demand than they are today. But for most people and their employers, the ever-changing, ever-more-technical task of writing is an alarming problem. The whole reason for our existence here at Contented.com is to solve that very problem.

I thank Dr Gupta for his clear-sighted speech.

About the author:

Rachel McAlpine is the Director of ContentEd.com.

About the illustration:

Used with permission from Nirupama Singh.

Possibly related articles:

1. CouncilSpeak – A Potion of Technology!
2. Who should manage a government portal? You!
3. Careers in Content Marketing

– Pranav

The morning of November 11 dawned fresh and clear.  There was a slight nip in the air but that was going to go away by the afternoon if I was any judge. Not that it really mattered.  I was probably going to be inside the hotel for the duration of the preconference workshops.  My introduction to STC India happened thanks to a friend referring me to the Society for Technical Communications.  I had decided to get into technical writing after a lot of soul-searching.  I was searching for a career where I could utilize my passion for technology and for books.  I was thrilled to find that STC had a chapter in India.  The mailing list was friendly, and surprise, surprise, a major technical writing conference was being held in Delhi!  Usually Bangalore has such “interesting” events.  Predictably, most of the writers I found were based in Bangalore or Mumbai.

Once I got over the initial astonishment of having such a significant event in Delhi, I registered immediately.  The problem as always came in selecting tracks.  I eventually settled on one and off I went.  It was fortunate that, all the tracks were held at the Sheraton.  If the original programme had been adhered to, I was in for at least an hour long car ride.

Conferences are exceptionally challenging especially if one cannot see.  Basic navigation is doable but the problem starts in “networking”.  For one thing, you don’t really know what the speaker looks like secondly there is no way for you to read name tags.  It is all very well to wear your conference badge but unless you are a speaker, it is not possible for you to either be noticed or, find the person you actually want to talk to. I did not fancy doing any talking. I was going to absorb information so this may not be such a problem.  I had decided to rely on my gut and go by the feel of the mailing list.  The volunteers were friendly and as happens in many such conferences, we had some interesting rescheduling take place.  I was in no mood to sit idle waiting for the initial session I had planned to attend. I found myself in the section on e-learning conducted by Thejaswini Uni.  There was something about Web 2.0 in the session title and I imagined things like action scripts and Flash running through my head.  There had been no teaser for the session which further increased the mystery.

It turned out to be a fortunate accident.  For one thing, I found myself seated with highly competent and outgoing teammates.  We had an instant frequency match and from there, we took the audience, on an African safari (visas not required).  It was fascinating to see how different groups treated the same concept differently.  For a change, we did not encounter any significant technology issues.  So no “mike testing check”.  I was not present for the hard-core software related workshops so I don’t know what happened there but otherwise, the technology behaved itself.  Murphy of course had to be somewhere so we did get into a few interesting scheduling clashes.  However, no one minded, especially in the panel discussions if a large bunch of orphaned delegates strode in late.

Lady luck must have had a grin on her face on day three.  I was able to make it for the session on freelance writing. Mr. Ravi Kumar, or raviwriter as he is known on the web, is a passionate freelancer.  The recession was proving to be the golden age for freelancing.  Everything was being outsourced.  It was a simple matter of finding a few customers and that was that.  A testament to the quality of the session is that we did get a glimpse of where to find these elusive customers.  The slides however flashed by too quickly for anyone to take any notes.  Still, those places are out there and I don’t think they are going anywhere. The rest of the day was spent cruising through different sessions based on chance and who I was with.  I had no defined plan so I attended a variety of sessions ranging from Adobe’s Web 2.0 offerings to commonly made management mistakes.

Finally, gentle reader, thank you for reading this far. It is time for this sponge to return to the deep to do some research since another deadline looms.

About the author:

Pranav is a freelance  copywriter. His website is http://www.pranavwrites.com.

He writes technical material as well as marketing case studies, brochures etc which is why he styles himself as a copywriter as opposed to a technical writer.

About the illustration:

Used with permission from Nirupama Singh.

Possibly related articles:

1. Report: STC India Career Day & Regional Conference
2. [Oct 2010] STC India Announcements
3. STC India Conference 2009

– Michelle Cherian

Its December and Christmas is almost upon us, and so is a brand new year 2011 fast approaching. A whole new STC India administration council will also take charge of our chapter and take the next steps forward! We do have a few new faces in our council next year, but we do encourage you to volunteer and help us grow and take the chapter to greater heights.

It has been a busy year for the STC India chapter with lots of activities through the year – learning sessions, regional conferences, webinars, blogs, annual conferences, SIG sessions and discussions, competitions, and mentoring program to name a few. Our recent successful annual conference at Delhi in November which attracted close to 250 delegates was a huge achievement for us, with the largest number of proposals and workshops received and enabled us to offer a wide variety of topics to the participant. Many of our overseas presenters and visitors had last minute visa problems which resulted in some cancellations, but a few of them arranged replacement speakers to share their presentations with all of us, and fill in the gaps. Our greatest challenge was planning the whole conference from way down south in Bangalore, and we thank our program manager Promila and our event manager Soumendra for ensuring the smooth sailing of the conference from Delhi.

In this complex world we live in, we need to wear so many hats. In my case, its mother, wife, daughter, sister, daughter in law, aunt, niece, grand daughter, technical writer, STC India chapter President. I am sure I  have missed a few of the hats. In each situation we play a different role and have to make a different impact. In our professional lives, being a volunteer with STC gives you an opportunity to work with other technical communicators in the industry and not just be limited to your team and your company. You get to share your skills and learn so much from seniors and juniors in the industry. In the bargain, you make good friends as well!

The first place that you can contribute is to this wonderful magazine of ours - INDUS. Thanks a million to Anagha and our INDUS team for the great job of timely publishing every two months! That’s really a commendable job! Every issue has been interesting and exciting and easily accessible online.

This year many technical communicators asked me why we concentrate so much only on the software industry considering there are so many genres of technical communication. We have tried to bring in the additional scope through our SIGs and leaning sessions on Corporate Communication and Instructional Design and Usability. But there still are a lot of domains that we do not cover. We do encourage you to help us identify communicators who can help us build the scope of the topics that we cover under our umbrella of STC India activities, we have a lot to do on the Education front as well as widening the scope of our activities.

We will continue in the coming year to build the capabilities of our portal, so that we can reach more communicators across the world. We encourage you to use these free services so that we interact more with one another.

Christmas is the time for giving and sharing, lets plan on what we can share with others under the STC India banner next year! All it takes is a little planning and some of your precious time to share with the rest of the fraternity.

A huge thank you to all our volunteers this year, especially our city representatives and SIG leaders who kept our lists and our activities going throughout the country. We do hope we will get many more dedicated volunteers in the coming year.

We wish you a Merry Christmas and a happy and prosperous new year 2011!!

In the words of Edith Lovejoy Pierce:

“We will open the book. Its pages are blank. We are going to put words on them ourselves. The book is called Opportunity and its first chapter is New Year’s Day.”

About the author:

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

Possibly related articles:

1. [Feb-2010] Prez Talk
2. [Oct 2010] Prez Talk
3. Prez Talk

The STC India Admin Council for 2010 would like to thank all the volunteers who made all the chapter activities possible and helped build the chapter this year. Special mentions are due to the following volunteers:

City Reps for organizing learning sessions in many cities:

-          Suresh Warrier – Chennai

-          Manoj Bokil – Hyderabad

-          Ramesh Aiyyangar – Pune

-          Naveen D’Cruz – Bangalore

-          Manisha Khurana – Delhi

2010 Annual Conference team:

-          Promila Chitkara – Program manager

-          Himanshu Marathe

-          Reema Khosla

-          Savita Thakur

-          Ashmita Bose

Competitions:

-          Preran Kurnool

-          Surag Ramachandran

Employment Manager:

-          Purushottaman

Mentorship Manager:

-          Sumedh Nene and his capable team of mentors

INDUS team:

-          Anagha Chandratrey

-          Manoj Bokil

-          Vikramaditya Urs

-          Sridhar Machani – instrumental in publishing INDUS using a brand new Web2.0 format.

-          Ashish Gupta

-          Savija

-          Anuj Kapoor

-          Anindita Basu

STC India Portal Webmaster

-          Sridhar Machani developed the brand new STC India portal.

Management SIG:

-          Ramesh Aiyyangar

-          Vijayashree Shreesh

Corporate Communications training course and SIG:

-          Peter Yorke

-          Tharun Unni

Usability SIG:

-          Arun Martin

-          Suman Ranganathachari

-          Xavier Roy

Other STC activities and Conference assistance:

-          Rajeev Jain

-          Shirin Rahman

-          Edwin Skau

-          Rachna Ganguli

-          Makarand Pandit

-          Susan Alexander

-          Pawan Nayar

-          Savitha Thakur

-          Preran Kurnool

-          Anindita Basu

-          Makarand Pandit

-          Vasanth Vaidyanathan

-          Manoj Bokil

-          Susan Alexander

-          Samartha Vashishtha, who developed the 2010 conference registration form. Thanks to the online facility, we were able to track all registrations online with minimal manual input!

Possibly related articles:

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

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

Delhi 11^th Dec, 2010

• Developing e-learning content using Adobe Captivate  - Suhas Yogin
• Creating Interactive PDF – Manisha Khurana

Both sessions were sponsored by Comviva.

Possibly related articles:

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

Path to Follow

STC’s Fellows and Associate Fellows are among the top technical communicators in the field. STC has implemented a program to recognize their valuable contributions to the field of technical communication. This program is called the Path to Fellow. Read more about the program and the honor here. Access all of them here.

Membership renewal

STC unveiled a Member-Get-a-Member campaign that can save members up to $50 off their STC membership! Members have to get colleagues and coworkers to join STC. You can vote in the elections by renewing your membership before 28 February 2011.

This year too, MadCap Software is offering to pay for your Basic membership if you purchase select software.

Community events

Many of STC’s communities provided information on their November events for the new Community Events page. Many events are virtual, and can be attended over the Internet.

Editorial calendar for Intercom

Editorial calendar for 2011 for Intercom is out. The editorial calendar is a product of brainstorming sessions about what content STC should publish in its magazine and what the trending or “hot” topics are in the field. It also provides guidance to potential authors. See the topics listed and decide which one is right for you

STC Summit

Registrations for California STC Summit have started on 1 December 2010. Check the new Summit website, for the preliminary program posted there.

Results of the Products and Services survey

STC recently released the results of the November Products & Services survey, conducted as part of the Project Phoenix initiative. The results, combined with some additional comments members provided, gave us a clearer picture of what products and services our members value and which they find the most important.

Salary database report

Sought after by job seekers and project planners the Salary Database report is available. STC’s Salary Database is a tool that can be used to conduct more powerful job searches, make a strong case for a raise, or prepare department payroll budgets. The data in the Salary Database are drawn from the United States Bureau of Labor Statistics (BLS) Occupational Employment Statistics (OES). Read more in this post on the Notebook blog.

The 2011 Slate of Candidates

Hillary Hart will automatically succeed to President from Vice President, but other positions are up for election. Click here to see the full slate. Please note that all STC members must have paid their dues by 28 February 2011 to vote in the election.

Announcements compiled by Indus task force member Ashish Gupta.

Possibly related articles:

1. STC Announcements
2. [Oct 2010] STC Announcements
3. STC Announcements

STC India Admin Council – 2011

Sandhya Prasad, the Election officer for 2010, announced the election results for the STC India Admin Council. The 2011 STC India Admin Council is:

• President: Rajdeep Gupta

• Vice President: Naveen D’Cruz

• Treasurer: Saravanana Manoharan

• Secretary: Swaminathan Moorthy

STC India Job Portal

STC India now has a jobs board and it is free for all. No registrations are required. Just visit http://careers.stc-india.org/, view jobs, and upload your resume. Your resume goes straight to the employer’s inbox.

Archives from the STC India Annual Conference

The presentations from the STC India Annual Conference held at Delhi are now available online for free download.

Some conference pictures can be viewed here and here.

Ravi Kumar was adjudged the best speaker at the conference.

STC India – volunteer of the year award

This year, volunteer of the year was awarded to

• Naveen D’Cruz – Best City Representative

• Arun Martin – for leading the Usability SIG and discussion group

• Anagha Chandratrey – Editor, INDUS

STC India Tech Pubs contest winners

The winners of the STC India Tech Pubs contest are:

• Tech Pubs

Shwetambara Pandey - Installation and Upgrade Guide for Sybase Databases
Chanchal Setia - Monitoring a VMware ESX/ESXi Environment

• Online communication

Suraj Jayan – HP SOA Policy Enforcer tutorial

• Technical Art

Vikrant Rai - Typography poster

For more details, contact Preran Kurnool.

STC India Salary Survey 2010

The results of STC India’s salary survey were announced at the STC India Conference. Click here for details.

Possibly related articles:

1. [Oct 2010] STC India Announcements
2. [Dec-2010] STC India Announcements
3. [Apr 2010] STC India Announcements

– Makarand Pandit

This is the final essay of a three-part series. Read part 1 here and part 2 here.

In the previous article we talked about Ratio Analysis. We looked at

• Frederick Ratio or Height Ratio
• Sunil Ratio or Width Ratio
• Mak Ratio or Distribution Ratio

In this part we will look at two techniques of time estimation.

1. Activity-based Matrix Technique
2. Topic-based Spreadsheet Technique

Activity-based Matrix Technique

This technique is fairly simple to use. It is a simple table that you need to fill.

Activity-based Matrix Technique

This technique is applied when a quick estimate is required. For instance the client might show a demo and ask for a quick estimate within two hours. The writing process is broken down into the various activities. The process of writing the document can be split into 3 drafts. You can consider having more than three drafts depending on the scope of the document.

Estimate the time that will be taken for each activity corresponding to each draft.

Ideally, the time taken for the subsequent drafts will go on decreasing. If the time taken is constant for all drafts or the time taken increases for the subsequent drafts then there is considerable amount of discrepancy in the structure of the document.

If we consider the activities, not all activities will be part of the all three drafts –

• Study time – It will only be applicable to first draft
• Writing time – It is applicable to all drafts
• Review & Changes – It will be applicable to drafts 1 and 2. It may not be applicable to draft 3 (or final draft)
• Packaging & Release – This activity includes work like binding, printing, page numbering and so on. It obviously won’t be required for the first 2 drafts.

Use the Matrix technique to prepare Minimum (Best Case) and Maximum (Worst Case) estimates. The ideal estimate will be somewhere between these two numbers.

Topic-based Spreadsheet Technique

This technique is a much more advanced form of the Activity-based Matrix Technique. Here we use a slightly more advanced matrix. It is illustrated in the table inserted below.

Here we calculate the time for every activity at the chapter (or topic) level. You would get an accurate estimate if you use the RCO (Rich Content Outline).

Topic-based Spreadsheet Technique

Once you get your total number of hours, you add a buffer to it. Typically, this could be around 15% to 25%. This should give you an estimated number of hours for the project.

Estimating Project Cost

Once you have the number of hours you can prepare the cost estimate. For this you will need to multiply the number of hours by the hourly rate. Do not forget to account for the items like Communications, Travel, Cost of hours already spent and Hardware/Software (Other Costs.) This calculation should look like the Project Cost Estimation Table given here.

Project Cost Estimation Table

Change the hourly rates depending on the complexity of the work and experience level of the resource. Change the numbers mentioned to suit any currency.

There is a ready-to-use Excel sheet prepared by the author. To get a copy, please send a mail to the author.

The author has already published an article titled Estimating Documentation Projects. This article is available as a free-download on www.stc.org.

About the author:

Makarand (Mak) Pandit is a technical communicator/trainer with over 17 years of experience. Mak runs a Technical Writing & Training Company – Technowrites Pvt. Ltd. Mak can be reached at mak@technowrites.com

About the illustration:

Used with permission from Mallika Yelandur.

Possibly related articles:

1. RCO, Estimation, & Ratio Analysis Technical Documentation, Part 2
2. RCO, Estimation, & Ratio Analysis Technical Documentation, Part 1
3. Applying the Wideband Delphi Method for Estimating Documentation Effort

VolXII, Issue 5

Let’s keep this short and sweet this time, shall we? For one, there are a lot of good articles in this issue. For another, I’m sure you’re all busy with preparations for the annual STC India conference in New Delhi. Capital! – as Lord Emsworth would say, I am sure. Last and not the least, the holiday season is in full swing. Here’s wishing you all happy holidays. Hope joy and good luck follow you everywhere you go.

In this issue, Mugdha makes a very important point about making your documents accessible to everyone.

We have an article by INDUS task force member Ashish, that shows you how to extract your content from a PDF if you need to reformat it.

Vishesh tells us how xml helps keep it straight and simple.

Makarand’s study of estimation, that we started reading about in the previous issue, is continued in this issue of INDUS.

Kumar Dhanagopal writes about the art of documenting instructions.

Prabu has some career advice, if you are wondering how to widen your horizons.

Ugur Akinci shares some insight on making your documents relevant to international readers.

Prasanna has an interesting piece that briefly traverses the history of the tools we use.

And finally Sumedh Nene provides answers to some oft-repeated questions about job-hunting 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, Nirupama Singh, and Vishesh Gupta are exclusive to Indus.

- 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 01st of Dec, 2010.

Possibly related articles:

1. July-August 2010 Newsletter
2. Nov-Dec 2010 Newsletter
3. Jan-Feb 2010 Newsletter

- Mugdha Vairagade

The software application you document is accessibility-compliant, but not the documentation you author? Then read on.

According to Wikipedia, accessibility is a term used to describe the degree to which a product, device, service, or environment is accessible by as many people as possible. Specifically, accessibility indicates how easily people with disabilities or special needs can access and use anything; ­ be it elevators, home appliances, websites, or software applications.

Today most software applications, from Office suites to authoring tools, either include accessibility features or support assistive technology. That is,

• Software applications have in-built accessibility features that enable the people with disabilities use those applications, such as text magnifiers, text-to-speech UI readers, voice-based navigation and so on. Or,
• Software applications are engineered in such a way that people with special needs can use special tools, broadly termed as assistive technology, to interact with these applications. The special tools include screen readers, Braille display, voice-based browsers and so on.

Government regulations (for example, section 508 Rehabilitation Act,1973 of United States) either encourage or make it compulsory for software vendors to make their applications accessibility-compliant. Market demands also dictate implementation of accessibility-compliance to reach a wider customer base. Accessibility-compliant applications not only help users with disabilities but also the users who want to use assistive technology as alternate means of application interaction.

With software applications implementing accessibility guidelines, it is only natural that their documentation too should be accessible. At present, organizations such as IBM, Apple, Oracle, and many others have set up accessibility guidelines for their documentation (see the Resources section). The documentation accessibility guidelines are similar to the Web Content Accessibility Guidelines set by World Wide Web Consortium (W3C), and are easy to implement.

Here are a few generic guidelines that you can use to make your documentation accessible to a larger audience via assistive technology:

1. Carefully analyze the audience of the documentation you are to author. Does that include people with special needs? Identify the groups of special needs users for whom the application and documentation is relevant. For example, an image editing application may not be useful for people with visual impairment, but can be used by people with speech or hearing disabilities. Therefore, the corresponding documentation should be written to be accessible to the later two groups.
2. Make documentation text easy to read and convert for assistive technology (text-to-speech reader, Braille browser, voice-based browser and so on). Take the following steps:
   1. Keep the formatting separate from text using style sheets. Then the assistive technology is able interpret and present the style information as per its own capability. For example, assistive technology may display different font and larger font sizes.
   2. If possible, use markups to indicate special characters, notations, and mathematical expressions. For example, use MathML for mathematical expressions in Online Help. Also ensure that special characters and notations are pronounced correctly by text-to-speech readers.
   3. Avoid using tables to specify page layouts. Assistive technology has difficulties interpreting document structure and flow of a document that uses tables for page layout.
   4. Online Help and DITA documentation authored using pure well-formed HTML, XHTML, or XML are best-suited for assistive technology. For such documentation, write content using only generic acceptable HTML/XML tags and avoid browser-specific tags/scripts. Also, follow points a, b, and c mentioned above. These steps help create documentation that is compatible with most tools used by people with special needs.
3. Avoid using visualization and colors alone to indicate something in documentation. For example, relying only on user interface screenshots to explain steps in a process, or using colors to indicate areas in charts or graphs makes it difficult for people with vision impairment to understand such documentation. The best approach in this case is to use alternative text or descriptive captions for images, and using text labels instead of colors for indication or highlighting.
4. When using tables, identify table cells and relationships between cells with column and/or row headers. Refer to Web Content Accessibility Guidelines (see the Resources section) to know more about creating tables readable by assistive technology in Online Help.

For other documentation types, include a short description before the table, to explain the purpose of the table and the table structure. For example, “In the Table 4.1 Variable Values, the column Variables contains variable name. The column Default Value contains the corresponding default values, and the column Range contains the corresponding range of values.”

1. If publishing a PDF, take steps to make the PDF accessible – using document structure tags, bookmarks, and text-to-speech capability. See Resources for PDF Accessibility Guidelines.
2. If it is not possible to provide one single set of accessibility-compliant documentation for both the general and special-needs audience, then create a separate set of accessible documentation, authoring all content in suitable form for assistive technology.
3. Make documentation easy to navigate; include search, bookmarks, and tags.
4. Provide keyboard shortcuts as alternative to any mouse actions required.
5. Provide text transcripts along with audio and video content. Also, provide controls to start, pause, or slow the speed of such content.
6. Like testing software for bugs, test documentation for accessibility. At present, various web accessibility checker tools are available (see the Resources section). Use them to test the Online Help documentation.

For PDFs, use Adobe Acrobat’s accessibility checks and reports feature. Microsoft Office 2010 also has in-built accessibility checkers to help you author accessible documents and presentations (see the Resources section).

This generic set of guidelines helps you to author all types of documentation that is accessible from most assistive technology tools. Do go through the organization-specific guidelines listed in the Resource section, to learn how to make a specific documentation type accessible.

Resources:

• W3C Web Content Accessibility Guidelines 2.0 (http://www.w3.org/TR/WCAG20/)
• Web Accessibility Initiative (http://www.w3.org/WAI/)
• Web Accessibility Checker Tools (http://www.w3.org/WAI/ER/tools/)
• PDF Accessibility Guidelines (http://www.adobe.com/accessibility/products/acrobat/pdf/A9-pdf-accesibility-overview.PDF)
• IBM Human Ability and Accessibility Center (http://www-03.ibm.com/able/guidelines/documentation/accessdoc.html)
• Oracle’s Accessibility Program (http://www.oracle.com/accessibility/index.html)
• Documentation in Accessible Formats for Microsoft Products (http://www.microsoft.com/enable/products/docs/)
• Apple Accessibility Overview (http://developer.apple.com/mac/library/documentation/Accessibility/Conceptual/AccessibilityMacOSX/OSXAXWhy/OSXAXwhy.html#//apple_ref/doc/uid/TP40001078-CH206-TPXREF101)

About the author:

Mugdha Vairagade is a Pune-based senior technical writer with 10 years of experience and specialization in Telecom domain. She became interested in documentation accessibility after learning about accessible Telecom services for people with disabilities.
You can reach Mugdha through her website (www.techatom.in), her LinkedIn profile (http://in.linkedin.com/in/mugdhav), or twitter (www.twitter.com/mugdhav).

About the illustration:

Used with permission from Vishesh Gupta.

Edited:

The link to the WCAG guidelines was updated to the link to version 2.0 as per Karen’s comment.

No related articles.

- Kumar Dhanagopal

Instructional writing is at a point today where most of us agree that adhering to certain writing styles can almost certainly make instructions more effective. Increasingly, organizations view the task of writing instructions as a rule-based activity that any person who can write reasonably well can perform routinely. Some organizations even invest in automated tools to ensure compliance with established style guidelines concerning parallelism, imperative tone, and so on. Organizations strive to achieve standardization in instructional writing: that is, ensure that every piece of writing bears a uniform organizational “tone” rather than individual writers’ voices. Written instructions are seen as mass-produced commodities rather than as unique pieces of art. In addition, with the entry of XML-based authoring, even the obviously “artistic” parts of technical communication—information layout and formatting—are automated. It appears, therefore, that instructional writing cannot be an art.

In this article, I argue that despite the seemingly mechanical context and nature of the underlying process of writing instructions, written instructions ARE works of art, because creative thinking and problem solving are essential to achieve the following goals of instructional writing.

• Convey complex information simply
• Address the needs of a wide range of users
• Balance conflicting interests
• Gather hard-to-find information from diverse sources
• Organize content based on audience needs
• Deliver content in a usable form

Convey complex information simply

Rules and guidelines for writing alone cannot help writers transform technical information into content that is easy to understand. A fair degree of iterative experimentation is required. In addition, often engineer-speak is complex because the creative thinking that occurs when a product is being engineered filters through into the speech and writing of engineers, rendering their text ambiguous and confusing. Technical communicators need to eliminate this confusion and ultimately improve the usability of the text (Byrne).

Address the needs of a wide range of users

Technical writers need to understand the language of the subject matter experts and that of the end users. Often, use cases should be imagined and anticipated. The right mix of textual and non-textual information elements should be used so that the information is useful regardless of the reading style of the user. In addition, the level of detail that different readers want varies: The instructions should be idiot-proof and yet not offend the sensibilities of experts who do not require handholding.

Balance conflicting interests

Technical communicators need to balance conflicting needs of stakeholders. Stakeholders in marketing might not want documentation to reveal too much about problems in the product. Developers would perhaps be happiest when the most hi-tech of the features is highlighted in the documentation. The user needs useful and usable information, just that and nothing else. Balancing these conflicting priorities requires tact and creativity.

Gather hard-to-find information from diverse sources

Information about how a product works (for example) is often not readily available, and so should be painstakingly discovered and harnessed from various sources. This activity is time consuming, requires enormous patience, and, most importantly, requires the use of creative “research and investigative skills” (VanArsdall).

Organize content based on audience needs

Depending on the needs of the audience, the technical communicator should decide how to organize paragraphs and sections, which topics should be reused, how topics should be interlinked, and so on. According to Sarah O’Keefe, “Technical communicators add the most value and have the most opportunity for creativity in crafting sentences, paragraphs, topics, and groups of topics that explain complex concepts to their readers”.

Deliver content in a usable form

The final output should be produced in a form that every user can find quickly and use, regardless of the condition of use. A car user manual that is provided in a DVD, as one manufacturer did recently, while certainly hi-tech, is practically useless. Understanding the usage environments and coming up with a delivery format that caters to all of them within the specified budget requires creative thinking.

Conclusion

Technical communicators need to understand audience needs; gather, write, and organize information, balance conflicting interests within and outside the organization they work for; and deliver complex information in a simple and usable form. Each one of these goals calls for creativity, imagination, and intuition—all clearly “artistic” qualities.

References:

• Byrne, Jody. 2006. “Suppression as a Form of Creativity in Technical Translation” (http://www.jodybyrne.com/176).
• O’Keefe, Sarah. 2010. “XML: The death of creativity in technical writing?” (http://www.scriptorium.com/blog/2010/02/xml-the-death-of-creativity-in-technical-writing.html).
• Rutter, Russell. 1991. “History, Rhetoric, and Humanism: Toward a More Comprehensive Definition of Technical Communication”.
• VanArsdall, Edward. 2010. “On Technical Writing and Creativity “ (http://www.vanarsdall-infodesign.com/2010/03/19/on-technical-writing-and-creativity/).

About the author:

Kumar Dhanagopal (kumards_99@yahoo.com) works as a senior doc project lead at Oracle.

About the illustration:

Used with permission from Nirupama Singh.

Possibly related articles:

1. 7 Ways to Avoid Misunderstandings When Writing for an International Audience

– Sumedh Nene

Greetings fellow writers!

Canada seems to be calling many Indus readers! What else would explain the numerous emails I am getting with questions – some serious, some curious and some, well, just downright practical – about this country of Loonies and Toonies (1 and 2 Canadian Dollar coins). Thank you to everyone that wrote to me.

So, in response to all the questions I received, I have put together this article in my ongoing efforts to unravel for you the secrets of Canada – which by the way boasts more donut shops per capita than any other country! While one reason to visit Toronto might be to see the CN Tower, the world’s second-tallest, free-standing structure at 1815 feet, immigrating here seems to pass through the minds of countless people. Just over 16% or 5.5 million of Canada’s population is immigrant and apart from the 2 official languages - English and French – the non-official languages widely spoken here are Italian, German, Chinese and… yup, Punjabi!!

As I said in my responses to many emails, if Canada is at the top of your I-want-to-immigrate-to destinations, think of specific reasons why that is the case – analyze your choice in the context of migrating, instead of going by the world’s popular perception of the country. That would be true for any country, of course. While I came here on a whim, literally, that strategy may not work for everyone. I took the traditional route of applying for a PR – waiting for approval – getting it and landing here. I am no immigration consultant, but there are 2 ways of  coming here for the long term: have a company in India sponsor your Work Permit (WP) or apply for Permanent Residency (PR) yourself.

Permanent Residency

A Canadian PR is easier than applying for immigrant visas of many countries. You qualify based on a fixed number of points that are awarded to various categories – your education, work experience, French and English language skills, money being brought in, immediate relations already  settled here, and so on. These cut-offs keep changing and the lowest I’ve seen are 68 and highest I think was 75. A few reasons why Canada is such a popular go-to destination are:

• You don’t need to be in Canada to process your PR
• You can be out of Canada for 3 out of a 5 year period and still have your PR renewed
• Time-to-citizenship is fairly short (approximately 4 years) from the day you land in Canada after getting your PR.
• PR is processed as a family, so you can include your spouse and kids in the same application. Currently it is taking about 5 years to process from India.

On the topic of PR, I would also add that you don’t have to go through an immigration consultant to file your PR application… it is fairly straight forward and there is a lot of help available on the Canada Immigration and Citizenship website.

To elaborate a little on the last bullet above, the PR is processed in family class, so while there is a principal applicant (you or your spouse – depending on who qualifies with more points), you include rest of the family (the other spouse and children) as dependants in the application. However, they are dependant for the PR application purpose ONLY – on getting the PR, they are treated as separate individuals in Canada. Whether the spouse gets a job or not completely depends on their skills and attitude. So, having a PR has nothing to do with getting a job. Often, the “dependant” spouse gets a job much faster than the principal applicant.

Work, Jobs and the Labor Market

Getting job in Canada is very different than getting a job in other countries. While not all, many employers need to have your credentials evaluated and most companies ask for Canadian experience, regardless of your seniority in another country. It is tougher to find a job if you are remote these days. With high unemployment rates and so many local resources available, employers have increasingly stopped considering people that apply form another province or city within Canada, let alone from a different country.

Best way of getting a job in Canada is to do some kind of local education / certification. There are several colleges offering Technical Writing degrees and diplomas in Toronto, and they are all very well recognized by the industry. While not knowing the latest trends like DITA isn’t a deal breaker, knowing it certainly would set you apart from the crowd. You might recall from my previous article, The Hidden Job Market of Canada, less than 20% of the available jobs are ever advertised. Here, over 80% of the openings get filled through networking and word-of-mouth. Linkedin is actually a very popular method of getting hired here and it really works. If you plan on coming here, begin investing some time and energy to build your references right now. Connect with writers here and leverage your association with STC India – seek out help from STC members in Canada. One good thing is that work timings in the GTA (Greater Toronto Area) are a non-issue – they are not as insanely demanding as in the US or India. People work 8-4 or 9-5 and that’s it. Working remote (from home) is not very common and you are discouraged from working over time. You do get paid 1.5 times for any OT you put in, though. So while you are out of office on time, the traffic in GTA isn’t always as kind. Commute times are generally horrendous – not because of the distance – but the traffic volumes. You’ll see when you get here J. I can almost guarantee the bumper-to-bumpers you saw on your last trip to US, may not have been the worst.

To newcomers, Canada may seem a strange country – jobs here are not given to seniority in terms of years of total experience, rather over your total Canadian experience. So, a person with a total of 3 years of writing exp. may get a job faster and be paid more than someone who has more than 7 years of experience, but outside Canada. As a full time employee, you can expect around 50k for 5-6 years and $40-70 an hour as a consultant (which is why many choose to incorporate here). But mind you, getting a job in Canada is tough, so come with an open mind and ready to face bit of a struggle. Other than that, I haven’t faced any major hurdles as an Indian or a foreigner coming to work here.

Most people begin their job-search adventures by attending a newcomer program. These are free (government-paid), 8-12 week, full day class room training that show you the ropes of job search techniques, the current labor market and things you wouldn’t know – till they told you – existed. Don’t come here hoping to have a resume ready, post it on job portals, call a few recruiters and start having an interview line-up. It’s tough business getting a job and takes blood, sweat, tears, time and plenty of patience and grit to get one.

Other tech-writer friendly destinations

Not all projects or every single document can be outsourced, and most IT-rich countries need the services of writers available locally. There is a steady need for writers in US and Canada all the time, but of course their demand & supply (availability) rides the economic curves. If you are looking for places with a growing market for technical writers right now, well it is India, hands down! Canada, US, Europe, all seem to be outsourcing to India and anyone relocating abroad, will be competing with their current colleagues in India. India’s economy at 9% is growing more and faster than any Western nation, so stay put in India and ride the surge. If you want to prepare yourself to relocate, consider Singapore and the US along with Canada. Get your paperwork ready and other formalities taken care of, so you are set to go as soon as the economy there starts the climb. Talk to recruiters who can do your H1 – look at Wipro, TCS, Infosys and see if you can join them and get projects through them… start such ground work now.

Final Words
Well, if you want to come here and give it a shot – by all means, be my guest. It’s a good place to be, once you are settled – for the long term. I would especially recommend it for those whose kids seem to be struggling with the Indian education system. Its easier on the kids here – they can enjoy life more without getting bogged down with the constant pressure of failing or being overtaken in marks by their friends. Cost of living varies and is very, very high in Toronto (I am not sure of rest of Canada, but I hear Vancouver is even more expensive.) There are taxes and fees and they are all steep. It’s almost impossible to give a ballpark figure of monthly expenses, but for rent (depending on area), expect to pay between CAD 1100 to 1600 a month (CAD 1 = Rs. 42). Car is almost impossible to do without – especially at the peak of a harsh winter, averaging -25^OC – unless you live in the downtown core of Toronto, where public transportation is better. Being one of the largest countries, there’s plenty to do and see and many water and winter sports to enjoy.

I’ve tried to paint a neutral picture, so you can appreciate both the positives and the drawbacks of this country. I am more than happy to share more specific work-related experiences as I have them – both as a full-time employee and a self-employed, running my own company, which I now am. Please do email me offline or feel free to leave your comments using the form below.

About the author:

Sumedh went to Canada in late 2009 to expand his India operations of CrackerJack WordSmiths Inc., and lives in Toronto. He is a visiting faculty on Technical Communications at the George Brown College and in September 2010 STC Toronto awarded him the President’s Award for his contributions as their Events Manager. He can be reached at sumedh.techwriter@gmail.com.

About the illustration:

Used with permission from Mallika Yelandur.

Possibly related articles:

1. The Hidden Job Market of Canada
2. The Canadian Blend

- Prasanna Bidkar

Technical communication existed in some form as early as the twelfth century, when Muhammad ibn Musa Al’Khowarizmi, a Turkish cleric, developed a writing method designed to achieve a specific goal. However, the last five decades have seen an explosion of technical inventions in the field of communication. The advent of computers changed the way documents were created and distributed. These rapid technological inventions also created a demand for clarification of technical information to people from all walks of life.
Looking back at the developments of the last few decades, we can say that there were three key phases of development in technical communication. The first phase spanned from the 1940s to the 1960s. This was the time technical communication moved toward being considered a profession. The second phase, 1960s to 1980s, was significant as there were major technological changes during these years. Advent of computer systems increased the demand for technical writers as the need to communicate these complex computer systems increased. The technology introduced word processing, information handling systems, and high speed printers. Technical writers had to adapt to using computer systems as well as understanding these systems to communicate the operational information to end users. We can say that the 90s saw the beginning of the third phase in technical writing with a hesitant movement toward hypertext in the early 90s.

In this article, I look at the changes dictated by the technological breakthroughs and research in technical communication, and the tools writers employed to make the information clear to the user. Most of the information in this article is from the Technology Review section of the STC’s Technical Communication journal volumes published from 1967 to 2003.

The Timeline
Industry needs and advances in technology governed the changes in tools used for technical communication initially. Research in audience analysis and need to reduce documentation cost later dictated the change in tools used to produce technical documents.

1940 to 1960s
The movement from traditional documentation and printing to automated documentation started during this time. The early 40s saw a shift towards specialized job responsibilities. Significant strides in technology were made during World War II and use of this new technology for consumer products increased the demand in technical documentation. The rapid changes in consumer product complexity also put an additional burden on the industry to produce technical documents at a faster pace.

Technology Breakthroughs
 IBM Corporation introduces word processing .
 Use of punch cards for indexing.
 Computer driven typesetting.

Tools
• PHOTON ZIP 901 for typesetting.
• Graphic Input System – GI/360.
• Electrostatic copier.
• Microfiche camera-processor.
• Text90.

1970s
The 70s took word processing to higher levels by providing centralized word processing capabilities for writers and editors to work on the same source.
Technology Breakthroughs
 Introduction of the concept of multimedia.
 Centralized Word processing–includes text entry, editing, and final output .
 Computers used to prepare master copy for offset printing.

Tools
• Mini computers–multiple terminals, one machine; examples include Astro-comp, DataText, and Compu-Text.
• Remote time-shared systems–examples include NLS (Stanford research institute), PCS/Text (Proprietary Computer systems), and WordStar.

1980s
This was a period of hectic activity with introduction of Hypertext and major advances in computer application. With faster printers available, organizations started to print manuals in-house bypassing the printer chain.
Technology Breakthroughs
 IBM Desktop PC launched.
 Xerox Corporation introduced the first WYSIWYG text and graphics merging software.
 Advent of information handling system. Movement from word processing to information handling, that is, sharing data/text across networks and use of databases.
 Adobe corporation introduced PostScript; a device and resolution independent printing language.
 The late 80s saw the introduction of computer based instruction and Hypertext.

Tools
• Ventura Publisher.
• DTP- LaserWriter and Linotronic 100.
• Word Finder (electronic Thesaurus).
• Microsoft Word – New features (redlining, macros, and so on.)

1990s
The 90s maintained the pace of the 80s and provided technical writers with tools to produce documentation customized for different audiences. Organizations were in a haste to convert their printed documents to online format.
Technology Breakthroughs
 Early 90s saw rise in use of hypertext media for document delivery.
 Introduction of SGML–although developed in 1986, its application in technical communication began around this time.
 Late 90s – Memory Translation tools.

Tools
• HyperCard; created by Bill Atkinson for Apple Macintosh.
• HyperTIES; developed at University of Maryland led by Ben Shneiderman.
• Authorware Professional developed by Macromedia.
• Doc-To-Help developed by Wex Tech System.
• FrameMaker developed by Frame Technology Corporation.
• SGML–Examples include DocuBuild, FrameBuilder, InContext.
• Memory translation–TRADOS translators workbench, Corel, Catalyst, IBM Translation Manager.

2000 – till date
With internet technology becoming the pivot of information delivery and an explosion of information, writers felt the need to simplify the documentation process as well as to provide information classified according to specific user requirements. The focus in this decade seems to be on improving the efficiency of writers and reducing effort by re-use of information.
Technology Breakthroughs
 Introduction of database supported information development.
 New concept of embedded help.
 Introduction of DITA.
 Single Sourcing concept.
 Web 2.0.

Tools
• Microsoft Exchange.
• Lotus Notes.
• AuthorIT.
• RoboHelp.
• IBM’s Information Development Workbench.

Additional reading:
O Hara, F. M. (2001). A Brief History of Technical Communication. Annual Conference – Society for technical Communitation, 48, pp. 500-504.

About the author:
Prasanna is a technical writer at Siemens PLM, in Pune.

About the illustration:
Used with permission from Vishesh Gupta.

No related articles.

- Ashish Gupta

When was the last time you regretted not having the source file of a PDF file you had to edit? Probably not long ago. We  have all lost source files to PDF files, only to realize later that the amount of editing we have to do cannot be done using even Acrobat. And then there are times when we’ve simply inherited or received PDF files from others, with no clue of their source files. While we learn how not to lose our source files (!), this article describes ways of generating them, starting with PDF files.

Acrobat, or for that matter any PDF editor, can only touch-up the text. For extensive edits you have to go back to the source files.

Acrobat includes tools to extract content that can save you a significant number of keystrokes that you would otherwise spend in re-typing. Do note that the way PDF format works, the best you can do is, extract the content with some formatting. It is difficult to retain formatting when converting from a PDF file. You have to re-format the content. Depending on the page layout and formatting, the re-formatting could be extensive.

How to extract content from a PDF file

The universally known, conventional option is to save PDF files in other formats using File > Save As in Acrobat. Use it to save PDF files in a rich text format or as a MS Word document. If you want to use the generated document in MS Word, then save it as an MS Word Document. If you plan to use the content (via say, importing) in any other application, then save as Rich Text Format. As we have all used this option often times, so I shall just give you a familiar looking list of all available options.

The File > Export option in Acrobat, is just a cousin of the above option. It provides almost all the options available in the Save As dialog (PDF and Optimized PDF formats are not present).

How to extract data from a PDF file

The best native methods of extracting data from a PDF file are, Saving as XML and Open Table in Spreadsheet options available in the Acrobat context menu.

To directly bring data into a spreadsheet program, select the data, right click on it, and select the Open Table in Spreadsheet option. The content menu is shown below.

Notice the Save As Table option in the context menu above. Choose this option, to save the selected data in CSV, XML, tab delimited, HTML, RTF, and txt formats. In one of these formats the data can literally be used in any application whatsoever.

Note: This option works best for the data which was originally formatted as a table in the source file.

How to extract images from a PDF file

Images get automatically extracted and inserted into the doc or RTF files. Also when converting to HTML the images are saved in a folder by the same name as the HTML file.

If you want to extract only the images, follow these steps:

• Go to Advanced > Document Processing > Export All Images.
• Choose JPEG, JPEG2000, TIFF, or PNG, as the file format.
• (Optional) Change the settings as desired. If you are unsure, export with the default settings.
• Select (or create) a folder in which all images should get extracted. Click Save.

Tip: You can prevent export of small and redundant images (like, thumbnails, company logos, advertisements in PDF files created from web pages, etc.) by setting the Exclude image smaller than option.

Note: Choosing an image format from the File > Save As dialog is not the right way to extract images of a PDF file. This option saves every page of the PDF file as an image and not the images contained in the pages.

How to extract content from scanned PDF files

You may need to extract content from a document scanned as a PDF file. Or you might need a soft copy document in editable format, from a hard copy document you have. Scanned PDF files are called image PDF files. The text can neither be copied nor edited. If you try selecting text the whole page gets selected and acts as if it is an image.

Optical character recognition (OCR) is the electronic re-generation of text present in scanned images into machine-encoded text. A limitation of OCR technology is that it can mis-interpret the optical characters. For example, i, l, and 1 can get mixed up. Hence for good results, it is mandatory, to proof-read the generated text.

Tip: Scan a hard copy at 72 dpi (at least) and in grayscale. For better performance 300 dpi or higher is recommended.

To extract text from an image PDF:

• Click Document > OCR Text Recognition > Recognize Text Using OCR.
• Select a page range to convert.
• Click Edit to open the Recognize Text – Settings dialog box. In PDF Output Style, select Searchable Image or Searchable Image (Exact). Image resolution does not matter. Click OK to run OCR, which creates editable content.
• Sanitize the generated content by correcting the suspect words.
• After the process, export into doc, RTF, text, or XML format as you would export from any regular PDF file.

Instruction to batch process multiple PDF files are available here .
Tip: If you have a long document, select only one page to begin with. If the quality is desirable then you can extract text from the whole document. Otherwise you may wish to rescan the document at a higher resolution.

Tip: An image of a document, taken from a digital camera, can be easily converted to an image PDF file, by printing to the Adobe PDF printer. By applying the same OCR technique, content can then be extracted from photographs of documents!

How to convert a PDF file to a FrameMaker file

Getting the content from PDF files into FrameMaker files involves two powerful features of FrameMaker and Acrobat software. This is helpful for writers who use FrameMaker as authoring tool and do not possess the source fm files.

• Using methods mentioned above convert your PDF files to RTF or doc formats.
• Import the generated RTF file into FrameMaker as mentioned here in FrameMaker help.

How to get more out of PDF conversion

For most of the file formats you select, Acrobat offers some customizable settings. For example, while exporting a PDF file to RTF format, the available settings are shown.

If you need only the text then do not include images. Images add a large overhead to processing. If needed for illustrative purposes only, you can downsample the images. Time taken to process images is significantly more than that taken for text. Leave tag quality settings unchanged. Tags are recreated only during the conversion and do not show in final document.

Similarly while extracting images from PDF files or exporting PDF files as images, the image settings can be customized to suit your needs of quality and speed. Read more here.

Do you have many PDF files to convert

In the File > Export list, notice that there is an extra option at the end. And a life saving one it is. You can set up a batch process using this option. Simply add your PDF files to the dialog box that opens and you are good to go. This could be a lifesaver especially in an enterprise setup, where there are lots of PDF files to be processed. This feature is available only in Acrobat 9 Professional and Acrobat 9 Professional Extended versions. Read more about batch sequences here.

Why copy-edit the generated files

Some text strings and handwritten parts, which are not very clear to Acrobat, come out as images in doc, RTF, and HTML output, and get missed out in the text or xml outputs. If they are present in doc or RTF files, selecting them would reveal that they cannot be edited. So after any conversion carefully read through the generated document. Manual typing or copy-pasting the text from PDF file is required to fix it. Also all conversions require you to format the re-generated source file, for reasons stated in the next section.

Why some PDF files do not convert properly

PDF is designed to be a final consumable format. All roads lead to PDF and arriving at any other format starting from PDF is inherently very difficult. PDF conversions talked above are not magic and are never 100% accurate. There are some PDF files which convert gracefully while others don’t.

While exporting and OCR features work smoothly for simple document, they partially work for heavily formatted pages, pages with highly customized layouts, or pages using decorative fonts. Tagged PDF files convert better, because they contain information on the structure of the content. In case of image PDFs, it helps to have a good resolution (about 300 dpi).

Note: If security restrictions do not allow you to open or dissemble a PDF file, then you cannot convert it into any format directly. You need the password (from its author) to enable direct exporting and editing in Acrobat.

How to extract content from secure PDF files?

Caution: Use this for personal PDF files, for which you own the copyright and have misplaced the password. Do ascertain your rights on the PDF files received from other sources.

If you have misplaced the source file, as well as, the password to your secured PDF file, use the following workaround to get your content back:

• If printing is allowed on your PDF file:
  • Print a hard copy.
  • Scan at highest possible resolution in grayscale.
  • Extract content from the image PDF as described above.
  • If printing also is not allowed on your PDF file:
    • Unix/Linux users can generate a PS file from the PDF file using the pdf2ps command.
    • Revert back to PDF format using the ps2pdf command. Re-generated image PDF file does not have the same font information and is inflated in size, but is not secured anymore.
    • Extract content from this image PDF as described above.

Do check out the cool export features in the upcoming Acrobat X here. Acrobat X has very powerful content extraction features, which will make all the above a cake walk. To explore more, visit the Acrobat product page here. (This article is based on the current Acrobat 9 family of products).

Your suggestions, tips, and comments are most welcome.

About the author:

Ashish works as a writer at Adobe India. He likes to trek, follow technology, and is a pro-environment hardliner. He can be reached on twitter @ashishguptaiitb.

About the illustration:

Used with permission from Nirupama Singh.

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 Adobe Captivate Tips
2. Creating Portfolios Easily
3. Five RoboHelp tips

– Makarand Pandit

This is the second essay of a three-part series. Read part 1 here.

In the previous article we talked about preparing the Rich Content Outline. In this article we are going to talk about the Ratio Analysis.

Ratio Analysis

The concept of ration analysis is popular in accounting and finance. The accountants apply some ratios to the numbers they have and try to predict the fiscal condition of the organization.

I have tried to apply the same principle to Technical Writing. I think Ration Analysis:

• Is generic enough to be applied to any type of document (independent of product, technology, deliverable format, delivery mode, and so on…).
• Helps to identify problems in the document’s organization.
• Helps to correct problems in document organization even before the document is written.

Before we go ahead and understand the rations. Let’s see what we are going to apply them to.

In the previous article we ended with a Rich Content Outline for the document. It looked something like this.

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

Now, let’s first generate some numbers here. For every topic that you see in the RCO try to predict the number of pages it is going to take. For the sake of estimation assume that we are talking about a standard A4 size page with 10 pt Times New Roman used for body text.

So, let’s look at Chapter 1: Introduction to Notepad. Let’s estimate pages for every topic based on the information contained in it.

Need of Word Editors                                                                                                                    (1 page)

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                                                                                                                                (1/2 page)

Information Organization Pattern: Most Important to least important

Graphic: None

Table: None

Procedures: None

Cross-References: Limitations of Notepad

Limitations of Notepad                                                                                                                  (1/2 page)

Information Organization Pattern: Most Important to least important

Cross-References: Advantages of Notepad

Types of files Notepad can be used to edit                                                                           (1/2 page)

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)

So, for Chapter 1 we will have a total of 1 + ½ + ½ + ½ = 2 ½ pages. Since ½ page is not practical, let’s round off the total to 3 pages.

Follow these steps and put down the number for every chapter you have in your RCO.

This may give you a table like this.

So now we have some numbers ready. We can start with the Ratio Analysis here. Let’s also calculate the ratios using these numbers and see what we get.

I have conceptualized three ratios. The ratios are named after three technical writers who came together to create India’s first University Recognized Post-Graduate Diploma in Technical Communication Course. These would be Frederick Menezes, Sunil Gokhale, and the author of this article Makarand (Mak) Pandit.

What are these ratios?

—  Ratio 1: Frederick Ratio or Height Ratio

—  Ratio 2: Sunil Ratio or Width Ratio

—  Ratio 3: Mak Ratio or Distribution Ratio

Frederick Ratio

FR = Number of pages of the biggest chapter/ Number of pages of 2nd smallest chapter

• This ratio indicates the difference between the biggest and the smallest chapter.
• This ratio by definition will not be less than 1.
• Ideally this ratio should be in the range of 5 to 7.
• It should not be more than 10 in any case.

Example of Frederick Ratio

With reference to the numbers given above, let’s calculate FR.

Pages of biggest chapter, Chapter 4, are 32 and that of the 2^nd smallest chapter are 4, then

Frederick Ratio = 32/4 = 8

Note: The reason I do not consider the smallest chapter is for exceptional reasons the document may contain a chapter that is only 1 or 2 pages (for example Quick Reference Chart, Installation procedure, and so on.) If this is the case, considering that number for calculations will give misguiding readings. If you are sure that this is not the case feel free to use the pages of the smallest chapter for calculating FR.

Observations: Frederick Ratio or Height Ratio

• Ideally value of FR should be in the range of 5 to 7. In our given example, it is 8. Which is not very good.
• If it is more than 10, it means the biggest chapter has ten times the pages than the 2nd smallest chapter.
• If the ratio is 1, it means all the chapters in the book are equal.
• Note that we do not take the smallest chapter. For exceptional reasons there could be a smallest chapter of only 1 or 2 pages (for example, Quick Reference or Installation.)

Sunil Ratio or Width Ratio

SR =  (Number of pages of biggest chapter / Number of pages in the Book) x 100%

This ratio indicates what amount of the content lies in one chapter. This ratio by definition will be less than 1.

So we consider it as a %.

Ideally this ratio should be in the range of 10 to 20%.

It should not be more than 30% in any case.

Example of Sunil Ratio

With reference to the numbers given above, let’s calculate SR.

Pages of the biggest chapter are 32 and total pages in the book are 115, then

Sunil Ratio = 32/115 = 27.8%

Observations: Sunil Ratio or Width Ratio

• Ideally this ratio should be in the range of 10 to 20%. In our example it is almost 28%
• If it is more than 25%, it means one fourth of the book is contained in one chapter.
• This will make the information in that chapter difficult to find.

Let’s look at the third ratio now.

Mak Ratio or Distribution Ratio

MR =     Number of pages in the book / Number of chapters

This ratio indicates how well the chapters are distributed.

Ideally this ratio should be in the range of 15 to 40.

Example of Mak Ratio

With reference to the numbers given above, let’s calculate MR.

Total pages in a book are 115 and total chapters are 10.

Mak Ratio = 115/10 = 11.5

Observations: Mak Ratio or Distribution Ratio

• Ideally value of MR should be in the range of 15 to 40.
• If the value is less than 15, it means you have distributed the book into too many chapters. There is a scope of to combine some of them. Or you can consider reorganizing the entire document. This seems to be the case with our example. On an average we have only 11 pages per chapter.
• If the value is more than 50, that means number of pages could be too high. So some chapters can be split.

Many interesting readings can be made if you plot a graph of the number of pages and chapter. For example, look at the graph below. It is drawn for the numbers considered in the example. You can clearly see that the information distribution is very poor in this document. There is information overload in Chapter 4. This gives rise to pyramid structure. This means the readers will be overloaded with information in Chapter 4 and get very little information in 1, 2, 6, and 7.

Poor Document Organization

I have found that many times new writers create document structures like this. The situation can be improved by changing the document structure and making it more flat. The figure given below indicates much better document organization for the same number of pages with much better rations.

Better Document Organization

Some more thoughts on Ratio Analysis

• The values of FR, SR, and MR, can change depending on type of document.
• The value of MR could vary a lot for different types of documents. MR becomes more significant in bulky documents.
• Some interesting observations could come up if you apply them to your existing documents. You can study any five manuals you already have and apply the three ratios to them. See what you get.
• The combination of these ratios may give some unique observations.

If you do any more work on this, please be in touch. I would like to know how this idea can be developed further.

About the author:

Makarand (Mak) Pandit is a technical communicator/trainer with over 17 years of experience. Mak runs a Technical Writing & Training Company – Technowrites Pvt. Ltd. Mak can be reached at mak@technowrites.com.

About the illustration:

Used with permission from Mallika Yelandur.

Possibly related articles:

1. RCO, Estimation, & Ratio Analysis Technical Documentation, Part 1
2. RCO, Estimation, & Ratio Analysis Technical Documentation, Part 3

- Vishesh Gupta

The characters:

KISS, The Guru

KISS is an acronym for the design principle “Keep it simple, Stupid!”. The KISS principle states that simplicity should be a key goal in design and that unnecessary complexity should be avoided. The acronym was first coined by Kelly Johnson, lead engineer at the Lockheed Skunk Works (creators of the Lockheed U-2 and SR-71 Blackbird spy planes, among many others).

The principle is best exemplified by the story of Johnson handing a team of design engineers a handful of tools, with the challenge that the jet aircraft they were designing must be repairable by an average mechanic in the field under combat conditions with only these tools. Hence, the ’stupid’ refers to the relationship between the way things break and the sophistication available to fix them.

KISS has been serving as a Guru for many, with XML being one of his disciples.

XML, The disciple

XML stands for eXtensible Markup Language. It is a markup language much like HTML, designed to carry data. Its tags are not predefined.

XML is a W3C (World Wide Web Consortium) recommendation. It was created so that richly structured documents could be used over the web. The only viable alternatives, HTML and SGML, are not practical for this purpose.

XML, simple and self-descriptive, has shot to fame all around the world in a short span of time. He has for long been a disciple and a keen follower of KISS. XML is modest and is easily available to anyone who wants to seek him out.

Mr. Tech Writer, The Modern Technical Writer

Mr. Tech Writer is a modern day technical writer who wishes to seek knowledge on documentation over the web.

* * *

The Conversation:

This is the part of the conversation that I was able to sneak up to and overhear…

Mr. Tech Writer: Sir, what is the purpose of your life and why should I appreciate you?

XML (smiling): In order to appreciate me, it is important to understand why I was created. I was created so that richly structured documents could be used over the web. The only viable alternatives, HTML and SGML, are not practical for this purpose.

HTML comes bound with a set of semantics and does not provide an arbitrary structure.

SGML provides an arbitrary structure, but is too difficult to implement just for a web browser.

KISS: Concepts are not to be multiplied beyond necessity.

Mr. Tech Writer: But Sir, are you compatible with SGML?

XML: I am compatible with SGML. Most of the people involved with me come from organizations that have a large amount of material in SGML. XML was designed pragmatically, to be compatible with existing standards while solving the relatively new problem of sending richly structured documents over the web.

Mr. Tech Writer: What about Single Sourcing?

XML: I shall make it easier for you to produce documents for many different output media (such as pdf, online help or the Web) from a single source.

Mr. Tech Writer: Are you easy to learn, write, and develop?

XML: If, like many people, you have never quite been able to get your brains around SGML but have been impressed by the possibilities for information publishing and retrieval offered by the World Wide Web, I could be the final piece of the puzzle that you’ve been looking for.

I shall be easy to create and edit. It is possible to create my documents directly in a text editor, with simple Shell and Perl scripts, etc.

KISS: Simplicity is the ultimate sophistication.

Mr. Tech Writer: Is it possible to tailor the layout of the same document according to the type of audience?

XML: Yes. Document types can be explicitly tailored to an audience. So the cumbersome editing that has to take place with HTML to achieve the desired layout shall become a thing of the past. You will be free to invent your own markup elements.

KISS: The simplest explanation is usually the best.

Mr. Tech Writer (a little confused): …my own markup elements?

XML (smiling again): You might be asking yourself how the web browser or document processing system can possibly know what everything means if you have defined it all yourself.

One answer lies in the fact that I shall enable you to specify the meaning or purpose of each document element in the markup. You can identify a book with a <BOOK> tag or copyright information using a <COPYRIGHTINFO> tag.

You can combine explicit tag names with explicit attributes:

<BOOK  NAME=”The Secret” PAGES = “206”>

Another answer lies in the use of Style Sheets. The Cascading Style Sheets (CSS) standard was developed by the W3C to address the problem of web document formatting. Originally designed for HTML, CSS is fully compatible with me and makes it possible to specify the appearance of custom markup elements using any of a wide range of possibilities.

And as I have already told you, I shall also work with other style sheet standards designed for SGML.

KISS: Make everything as simple as possible, but not simpler.

Mr. Tech Writer (innocently): So, sir, is it right to call you HTML++?

XML (smiling harder): You can call me ‘SGML–‘ rather than ‘HTML++’! I provide all the advantages of the powerful content-based markup and scalability of SGML while enabling business documents to be published as easily as is currently possible with HTML.

KISS: Of two equivalent theories or explanations, all other things being equal, the simpler one is to be preferred.

Mr. Tech Writer (smiling): How do I go about convincing my boss?

XML (sarcastically): Well, you can name a Markup Tag after his name!

KISS: ‘Keep it simple, stupid’

Note from the author: The intent of this article is to highlight the simplicity and advantages of XML in Technical Documentation.

About the author:

Vishesh Gupta is a B. Tech in Electronics and Communication Engineering from Amity University and has been working at STMicroelectronics for a year, with the technical documentation team. When he is not working he likes to paint, write, listen to music, play football and with programming codes, not always in that order!

About the illustration:

Used with permission from Vishesh Gupta.

No related articles.

– Ugur Akinci, Ph.D.

Technical communicators are increasingly catering to an international audience due to the expansion of the global market place. Such a development requires a new vigilance when writing technical documents in order to minimize inadvertent cross-cultural misunderstandings.

Here are 7 things to watch for when writing for an international audience (like I’m doing now):

(1) Watch for your date formats.

In the United States the date is always written with month first, day second, followed by the year as in 10/3/2010 for “October 3^rd, 2010.”

But in a lot of other countries the same date would translate as “March 3^rd, 2010” since day is written first, followed by the month and then the year.

To eliminate such mishaps completely, always write the month in open form, as in “October 3^rd, 2010” or “3 October 2010”.

(2) Watch your large numbers.

A “billion” is not always a billion. It just depends on which country you’re in. For example, in USA, a billion has nine zeros following a 1; but in most European countries it has 12 zeros following it. In Britain, ten to the power of nine is called a “milliard” and not a billion.

A “trillion” has 12 zeros in USA but 18 in Britain. And there are many other large numbers which are interpreted differently in different countries.

So check and double-check your figures to make sure they’ll translate correctly across cultural boundaries.

(3) Watch the way you punctuate your large numbers.

In the United States, a comma is used to separate the triple-digits of a long number for easier reading, and the period is used for a decimal point. For example: $ 4,345 (Four thousand three hundred forty five dollars).

But in some other countries (like Netherlands or Turkey) the decimal “point” is actually a comma, and the period is used for thousands separator. The above amount ($4,345) for example would be read as “four dollars and three hundred forty five cents” – which of course would not make much sense. To read correctly, the same amount should be written in countries like Netherlands and Turkey as $4.345 – with a period.

Always check the local punctuation conventions to avoid a surprise error.

(4) Be formal and polite.

In the United States most people do not mind receiving an email or letter from someone they don’t know that addresses them with their first name. In many other countries that would be perceived as a personal insult. Usually people like to be addresses formally, unless they are very familiar with the other person.

If you offend the other person needlessly by the way you address them you may lose your credibility without even being aware of. Thus play it safe and never get too personal in your communications.

For example, here is how not to start a letter written to a receiver in another country:

“Hey Janos! What’s up bud?!

Long time no see. You guys are ignoring me or what? I mean, it’s been a whale of time since I’ve sent you guys the invoice for that May shipment…”

Instead, try this:

“Dear Mr. Janowski,

How are you since the last time we’ve talked at the Microsoft Conference? I hope all is well with you and your family.

I’m writing to see if you’ve received our May shipment and if the product satisfied your expectations. As you know we always try our best to deliver what we promise and then some.

I also hope you’ve received the Invoice for that same shipment. If you have any questions I’d be happy to answer them for you. I’m attaching a second copy of the Invoice with this letter for your convenience and kind attention…”

The short path is usually the wrong path to the hearts and minds of the people that you don’t know too well. When in doubt always choose the “long path” and address them right.

(5) Avoid sports analogies and metaphors.

Cricket is the national sport in India and Pakistan but no one watches it in USA. American Football is all the rage in the United States but no one cares about it in most other countries.

People do not necessarily watch the same sports and thus they are not necessarily familiar with the same sports analogies and metaphors. Be very careful about the way you use sports language in your technical documentation because it may not mean anything for your readers from a different cultural background.

For example, avoid this: “We assure you that we won’t try to resolve this project bottleneck with a Hail Mary pass by installing an untested Prion server.”

If you are not familiar with American football you’d have no idea what a “Hail Mary pass” is.

Instead, write: “We assure you that we won’t try to resolve this project bottleneck with a desperate last-minute measure such as installing an untested Prion server.”

(6) Avoid military analogies and metaphors.

Same lesson: all readers are not familiar with military terms and concepts yet some writers don’t mind using them in their documents. It’s a mistake. Avoid blending in military analogies and metaphors with your technical writing in order to eliminate inadvertent understandings.

For example: “Monday is the D-Day for our new product launch.”

Better: “Monday is when we’ll be releasing our new product to the market.”

Another example: “The message is relayed down the chain of command from the Master module to all the downstream boards in the network.”

Better: “The message is relayed from the Master module down to all the downstream boards in the network.”

(7) Avoid colloquial and idiomatic phrases.

There is no better way to confuse readers from a different cultural background than using local idioms and colloquial expressions. Avoid them like the plague!

For example: “Consult Chapter 6 of the Troubleshooting Guide if you smell a rat.”

Better: “If you suspect there’s a problem, consult Chapter 6 of the Troubleshooting Guide.”

Another example: “If you do not upgrade your systems you’ll eventually pay though the nose.”

Better: “If you do not upgrade your systems you’ll eventually pay a steep price for your neglect.”

About the author:

Ugur Akinci, Ph.D. is a Fortune 500 Senior Technical Communicator sharing his free writing tips and tutorials at http://www.TechnicalCommunicationCenter.com

About the illustration:

Used with permission from Nirupama Singh.

Possibly related articles:

1. Technical Writing to Localization – An Emerging Career Path

- M.D.S. PRABU

Careers in Sales and Marketing were long restricted to a few designations like Salesmen, Marketing Executives, Cold-callers, Sales Managers. But, now there are a plethora of opportunities and one can be an Account Manager, Ad-Sales/Operations Manager, Marketing Communication/Brand Communication Manager, Pre-Sales person, Customer-care Representative, Business Analyst so on and so forth. The opportunities for marketing professionals are endless and it is ever-expanding with the emergence of a multi-million dollar industry, namely Content Marketing.

Possibly related articles:

1. Content: The News Marketing Tool

– Michelle Cherian

On behalf of the STC India Admin Council – 2010.

Just like the words in the poem – The road not taken –  written by the famous American poet Robert Frost, this year we chose the road less travelled by – and we hope our decision made a difference.

Hosting the conference in Delhi has been a dream of many an STC admin council-member, but most well wishers had advocated against. We took up this challenge early this year after a poll that went in favor of Delhi as the venue. The decision, planning, and execution was as difficult as everyone had predicted earlier, but, despite each hurdle we encountered, we have also found support in the form of sponsors and volunteers to help us tide over every one of them. Our panel of judges have tried bringing the best value and variety to the conference with the careful evaluation of over 100+ proposals and workshops.

With the huge hike in STC membership fees, we have tried to add as much value to the member locally. All our learning sessions and conferences are free for members. We also introduced a number of new initiatives, the Special Interest Groups (SIG) being some of the most popular, the Usability SIG being the most popular. We have also successfully run the mentorship program, and a variety of competitions throughout the year. We have tried to introduce the broader scope of Technical Communication, via Corporate Communications, and E-learning. We have made modest beginnings with the Management SIG and Instructional Design SIGs as well. Our Jobs Portal is quickly gaining popularity with jobs posted almost every week. It’s a completely free service for both the writer and prospective employer. The STC India network is the first attempt to have a social-networking and blogging setup to encourage more interaction amongst members for STC India. We have to work to get our members to use these facilities more.

This is the first year that we will have an online election. Many more people have come forward to volunteer for admin council positions. STC is one of the best forums to showcase your technical communication skills. As a council member, it’s a very fulfilling opportunity to serve the community. This year we – the admin council, thank you for the wonderful opportunity to work and take STC India chapter forward.

The strength of our community lies in working together, sharing with one another, to continuously improve the global visibility and recognition of the talent and skills of our members across the globe. Our annual conference is the ideal venue to do this. We do hope to see many of you at our conference which is the culmination of our efforts this year! Do register and participate and make it a resounding success!

About the author:

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

Possibly related articles:

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

12th Annual STC India Conference

The 12th Annual STC India Conference will be held in Delhi from November 11-November 13 2010.

Click here for details.

Click here for the conference agenda.

Click here for registering. Hurry, the registration closes in a few hours!

Admin Council elections

STC India Chapter members will be voting online this year to elect the admin council for next year. Voting will remain open till Nov 4, 2010. If you are a member, and haven’t received voting instructions by email yet, please write to Swaminathan Moorthy <swaminathan.moorthy@gmail.com> right away.

Possibly related articles:

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

Announcements compiled by Indus task force member Ashish Gupta.

Possibly related articles:

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

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

Bangalore October 23, 2010

The STC India User Research and Usability SIG organized the following sessions

• Effective Content Writing by Sudhindra.V, Sapient
• Content Strategy – Integrating Content in User Experience Design by Neha Singh and Arunima Saboo, Yahoo
• Documentation Deliverables for UX by Xavier Roy, Bally Technologies

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

Possibly related articles:

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

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. July – August 2011 Newsletter
2. Sep-Oct 2010 Newsletter
3. Jan-Feb 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.