Volume 2

Issue 4

December 2005

Case Study Agile Software Tanya Stevenson Founder, Zation Limited tanya.stevenson@zation.co.nz This case study discusses the use of a content management system to overhaul the documentation environment of a small software company. The company, which creates computer telephony software for the international contact center market, required user manuals and HTML Help in 12 languages. AuthorIT was selected as our content management vendor. Before this migration the company stored all its user material in Word files and ran an unreliable macro on those files to create WinHelp. Documentation existed in only four languages. The project, which spanned two years, was implemented by a single staff member. It started with AuthorIT Version 3 and later moved to Version 4 and AuthorIT's Localization Manager. About Agile Software Agile Software develops powerful contact center software for Avaya, a world leader in IP telephony, voice messaging and contact centers. Branded by Avaya as Avaya Contact Center Express, the suite of desktop and server applications is fully compatible with Avaya's switch technology (namely Avaya Communication Manager and Definity systems). Contact Center Express caters for contact center enterprises of any size. Its products embrace all the ways businesses and their customers communicate, whether it be voice, email or web chat. Maximizing the effectiveness of this communication is central to the suite's design. Like Avaya technology, Contact Center Express is sold around the world; in the United States/Canada, Europe, Latin America and Asia/Pacific. Background Two years ago all the company's user material was stored in Word files. Manuals were converted to PDF for distribution on the released CD-ROM, and application Help (WinHelp) was created by running a macro on the Word files and compiling the RTF output in MS Help Workshop. The company was putting out a range of products but only one of them was multilingual, its flag-ship desktop application called Agent. The Agent User Guide had been written in English and translated into three other languages - Japanese, Chinese (Traditional) and Chinese (Simplified). The documentation was managed by one staff member, a technical writer with four year's experience. Translation was outsourced and done straight into Word. Sales and marketing initiatives were emerging to support more languages - the requirements were likely to be French, German, Spanish (Castilian), Spanish (Colombian), Portuguese (Brazilian), Italian, Korean and Russian. What's more, other user manuals were going multilingual. Agent was no longer alone . . . The Challenge Before the content management system was introduced there were several issues: The macro we used on Word documents to create Help was unreliable and limiting. It only supported English, Japanese, Simplified Chinese and Traditional Chinese. No other language had been tested. It only supported Word 97. Word 2000 had not been tested. It relied on strict Word formatting, for example, carriage returns after tables and between text and section breaks. It was not robust. Sometimes there were unexpected formatting issues, especially with numbering. You had to bookmark text you wanted to delete (e.g., title page, Table of Contents, Chapter overview headings, Index) as well as headings you wanted to prioritize in the tree-structure. Bookmark names had to abide by the macro's naming convention. Creating a pop-up or jump hotspot was possible but it was a painful 26-step process. If running the macro produced errors, the RTF file had to be changed directly. When the macro was rerun, those changes were overwritten. The topic title area of WinHelp was character-limited (non-scrolling) and many procedure headings (especially when translated) were truncated. Editing often meant sending text back to the translator, an annoying and time-delaying process. The staff member who created the macro had since left the company and was not available for upgrading. Note: The macro converted a Word document, in a prescribed format, into a RTF file. The RTF file was then converted, using MS Help Workshop, into a help file. WinHelp as a format was not user-friendly. Its navigational tools (table of contents, index, and full-text search) were not in the same viewer window as the Help content. If a user found a word in the index and clicked it, the index would disappear as soon as the content appeared. To get the index back, the user had to click the Help topics button, at which point the content disappeared. Our software product names had changed once and were likely to change again. This meant a full search/replace of every document, and the risk of missing an instance of the name. Managing Word documents was becoming more difficult. Formatting text and updating changeable objects such as table of contents, footers and the index was a constant concern. As more products were added to the suite, it was becoming hard to keep up with documentation and manage an increasing number of Word documents. Text that was common to many documents was being copied and pasted from one place to another. Any changes to this common text had to be made in several places and finding the text relied on the technical writer's memory. Word documents required regular saving to a backed-up network drive. Copies also had to be saved to Visual SourceSafe so other staff members could access them. The biggest challenge to addressing our issues was finding the best help authoring tool. By searching the internet, calling other documentation specialists, and talking to software distributors, we narrowed the choice down to AuthorIT. The Solution The most attractive feature of our chosen content management system was its development work towards multilingual support. My research at the time gave me the impression that no other help authoring/content management tools could manage the localization process via a single application. In the case of RoboHelp, there was an English edition, which supported the Roman languages and Russian, and a separate Asian Edition, which supported Japanese, Korean and Chinese. We wanted one integrated tool that would allow us to minimize translation costs and reliably create good-quality HTML Help for all our languages. The valuable and essential addition of the content management systems localization module allows us to support an unlimited number of localizations. Our Current Environment Today, our English source library contains documentation for 25 software products. Documentation takes the form of user manuals, developer guides, help files (WinHelp and HTML Help), installation manuals and overview guides. Four user manuals have been translated into 11 other languages. We now manage a translation process with 11 target libraries: Chinese (Simplified) Chinese (Traditional) French German Italian Japanese Korean Portuguese (Brazilian) Russian Spanish (Castilian) Spanish (Colombian Variables (conditional text) Approximately 50 variables are used to manage product name changes. In a software environment where the name of a soon-to-be-released product is likely to change from that used during the early stages of development, variables have been a huge business benefit. What's more, ongoing efforts to improve product marketability mean names are always subject to change. Already, our product suite name has changed twice, and, in one major move, the word 'Active' was dropped from the beginning of every product name. Our system has allowed us to be exceptionally responsive to these business requirements. Shared objects Countless objects and pieces of text are shared between documents, making updates a one-step process: Topics Images Diagrams Glossary terms Software license agreement Copyright notice Chapter headings Website hyperlinks Company logos Title pages Buttons common to many product interfaces Configuration parameter descriptions Security User groups and folder permissions give developers and testers the ability to modify documents that relate to their job. We have access user groups for Developers, Testers, Trainers and Authors. Each software developer has their own login, with access permissions that allow them to modify developer guides related to their product area and read/print all other material in the library. This is particularly helpful if your usual technical writing staff do not have the knowledge essential to write highly technical documents like this. The Benefits There were benefits galore when we moved systems: 1. Fast We could create new user manuals far more quickly by using the drag-and-drop interface and reusing topics from other documents, for example, title page, copyright page, software license agreement, document conventions, knowledge base, error logging (standard to all applications), install procedure (standard paragraph reference to Installation Guide), glossary terms, configuration file parameter definitions. We were no longer wasting time and effort guaranteeing the correct format of our file outputs. Proper formatting is now a reliable given and we focus on document content. 2. Financially effective Due to substantial efficiencies, we avoided the likely requirement of employing another documentation specialist. We were no longer paying translators to translate sections of text that are generated automatically, for example, table of contents, chapter content summaries, and index. We were no longer paying translators to translate previously translated topics. Even when there were topic updates, translation memory capability (Trados) meant we were only paying top price for the new or altered text. 3. Quality software We could deliver HTML Help in all our supported languages - English, French, German, Spanish (Castilian), Spanish (Colombian), Portuguese (Brazilian), Italian, Japanese, Chinese (Simplified), Chinese (Traditional) Korean and Russian. We could guarantee a consistency of quality between documents. 4. Flexible We were no longer scrutinizing every document when there was a product name change. A variable was changed in one place and viola!, it was done. Our technical writer could continue to work from home when needed using a mobile off-line library technology. We could add a new language quickly and easily. 5. Modern HTML output We were able to offer users HTML Help and its more friendly navigational structure. With HTML Help, the table of contents, index, and full-text search are in the same viewer window as the help content pane. Users can always keep track of where they are in the help system and will never get "lost in cyberspace". What's more, HTML Help supports advanced full-text searching. It allows compound Boolean searches and enables users to search the results of previous searches so that they can systematically narrow the focus of their searches until they find what they're looking for. We could create hyperlinks in a single step and use them in all our target languages! 6. Reliable We were no longer vulnerable to the idiosyncrasies of the old macro. We had a reliable system that output Word and Help files the same way every time. We were longer double-checking that Word table of contents and page references were up-to-date. Our system automatically and accurately generated field elements during output. 7. Secure By keeping our AuthorIT databases on a SQL Server, we were no longer worried about the location of Word documents for securing and storing our source material. Developers, testers and other members of the company could only modify material related to their job area. However, they could read and output any document in the library. Localization Management With four user guides in 11 languages, we currently take 44 translated user guides to market. Because of Localization Manager our translation process is well structured, logical, user friendly and efficient. Without Localization Manager, managing updates across 12 languages would have been a huge manual job subject to human error. The automation provided by the system severely reduces the risk of error. By implementing Localization Manager with a carefully structured English source library, the benefits of sharing objects is migrated across all our target languages. The efficiencies of object sharing has saved us from employing more technical writing staff. Conclusion In conclusion, we are very happy with our chosen content management system. We no longer use the time-consuming and unreliable macro that limited us to WinHelp only. We have a single product that allows us to output Word documents and HTML Help in all 12 languages we support with our software. Output is initiated by a click of the mouse and, once our templates were set up correctly, files started looking the same every time - no horrible formatting surprises. With the introduction of Localization Manager, managing the translation process across 12 languages is orderly, logical and less vulnerable to human error. What's more, the benefits of object sharing within the English source library are transferred into all our target libraries - minimizing translation costs and speeding up the documentation process. Documentation is stored in secure SQL Server databases and user access permissions mean users can only modify material that relate to them. Last-minute product name changes aren't a problem. By using variables we only have to make the change in one place. Best of all it didn't take a substantial budget or project to implement, yet allowed us to highly customize our outputs. The results were plentiful and resulted in better content for our end users: Cumbersome localization process's became streamlined and cost efficient. Reuse of content was as simple as dragging and dropping. Best of all, we didn't need a large enterprise size budget to achieve it.