Using Author-it and Sajan to Improve the Efficiency of Localizing WebEx Support Content into Ten Languages

Felicia Wu, Cisco WebEx • Milpitas, California

The Cisco WebEx documentation group of five writers creates end-user and administration documentation for all the WebEx services and various integrations with third-party products. Since Cisco acquired WebEx in 2007, our team has not grown in size. But, the number of products we have to support has grown. We also work with a localization team to produce these documents in 10 languages. We had these challenges:

• Smallest "chunks" of information writers could reuse were "modules" (a group of 10 or more topics describing how a feature worked).
• Framemaker's features, such as conditional text, were useful, but we ended up with complicated documents requiring a color-coded legend to understand.
• Output could not be shared across the enterprise.
• Feature-oriented, rather than task-oriented documentation, was provided.
• High costs for localized desktop publishing and creating localized screenshots

Shortcomings in the localization process: In our quest for the right tool that allows the documentation and localization teams to gain efficiency, propagate content to diverse groups, and streamline localization through content management, we had evaluated various tools and finally decided to purchase Author-it because of its versatile content management system. Later, the localization team also chose to partner with Sajan, which is able to utilize our streamlined Author-it content.

With Author-it, we are able to:

• Save the content (as objects) in a library (database), available to all writers. Topic objects can be as small as a sentence or topic heading. Other objects can be graphics, index entries, and cross references. Objects can be recombined and reused in new and creative ways.
• Automate processes to improve efficiency, such as assigning "states" to objects and managing the workflow from draft text to final localized topics. When a writer updates an object, the changes automatically reflect in all places where the object appears.
• Create and manage multiple books for each WebEx service and share topics across services using one source.
• Collaborate more freely with each other and with other teams.

Since Cisco WebEx started leveraging the Author-it platform for creating content and Sajan's localization platform GCMS for localization, Cisco WebEx has increased the number of languages from seven to 10 and decreased the cost of localization by more than 60%.

I have been a technical writer at Cisco WebEx for nearly eight years. As the documentation team member with the longest service period at WebEx, I have seen how our team has transformed from documenting in the linear, traditional way to single-sourcing, sharing, and reusing the content. Besides documenting our various services, I also dedicate much of my time in working with cross-functional teams to provide useful information in our services at the right time, in the right amount.

Using Adobe AIR to Enhance Help with Web 2.0 Features Like Commenting and Favorites

Becky Williams, Harris Corporation • Englewood, Colorado

In the fall of 2008, Becky started working on user assistance for a new software product targeted to the emerging digital signage market. The product operates similar to other Harris products in the broadcast industry; however, the digital signage audience is diverse and unfamiliar with these systems and terminology. Because of this, Becky felt it necessary to have direct feedback from the users in order to know that they were getting the guidance they needed to use the software. In addition, she sought a way to update Help between software releases in order to provide key information in a timely manner. The optimal solution was something more than the traditionally, passive reporting provided with RoboHelp Server. With RoboHelp 8, Adobe added a new output option that creates an AIR application and displays the Help within the updatable application viewer. This output, in addition to having an updated look-and-feel, includes Web 2.0 features such as commenting and favorites. During the product's prerelease program, Becky learned that these comments can be shared not only with other users at a company location, but also with her as a method for receiving rich client feedback. Project challenges included revising the CSS to accommodate new list styles, understanding how the AIR application is installed and called when using context-sensitive Help, and implementing the solution with a web application, which is the most difficult of the AIR integrations. In order to surpass these hurdles, Becky had to blur the lines between writer and developer.

Becky Williams has been a technical writer with Harris Corporation for 8 years, although her interest in assisting users started with her first computer interaction in the mid-1980s. She develops Help, documentation, training tutorials and SharePoint portals for three Agile Scrum teams in New Product Development for the Broadcast Communications Division. Becky is an STC member and the Rocky Mountain Chapter's Web site co-manager.

Supporting a Diverse Audience by Employing Author-it "Variants" to Embed Client-Specific Content on Demand

Chip Jones, ADP Comprehensive Outsourcing Services • Roswell, Georgia

In support of Sarbanes-Oxley compliance requirements, our business unit needed a way to publish a standard set of internal operating procedures that also incorporated client-specific content--in context--within many of these procedures. With over 60 clients across three payroll systems, we determined that Word, Frame, and the HATs do not provide the required features to support this level of conditional publishing. We also required a tool that strongly supports both reuse and single-source publishing to PDF and HTML outputs. We selected Author-it based on its support for all these needs, but the key feature was the support for "variants" that was added in version 5.1. With variants, we can create one-off topics that retain and reuse the core content but also include the unique content as fully formatted, embedded objects. (Earlier Author-it releases did not support formatting the text within variables.) At publishing time, we can then use the variant feature along with variables to create sets of documents that pull and embed the client-specific content on demand. With Author-it's support for publishing profiles, we can also set up profiles for each client and direct the published outputs to specific folders on our dedicated web server, significantly reducing the need for manual intervention.

Chip Jones is a technical writer at ADP and an adjunct professor at Southern Polytechnic State University. He has worked in user assistance for over 20 years and formerly managed a large team of writers and editors at Ceridian. Chip is an Associate Fellow of the Society for Technical Communication, where he formerly managed the international online communication competition, and he has presented at many national and international conferences.

Using Innovasys Document! X and HelpStudio to Extract XML Comments from Code and Single-source to Multiple Help Outputs including Visual Studio Help 2

Lisa Saunders and Rachel Samuel, Accusoft Pegasus • Tampa, Florida

Background: Documenting Application Programming Interfaces (APIs) for developers who use our Software Development Kits (SDKs).

Description of application: There is no user interface. We document API objects, classes, methods, properties, and enumerations for developers to use when they code applications using our SDKs.

Challenges: Delivering online help systems in three ways: standalone help from the Start menu, web-based help from our website and Help 2 API output that is integrated into Visual Studio. There was also the challenge of going through a company-wide rebranding effort with new colors, logos, and file naming conventions.

Tools: Innovasys' Document! X and HelpStudio are used to develop and deliver the three outputs. It is the best tool for pulling XML comments from the code and for providing general help and API help in one seamless output.

Key features: The user has the ability to refer to and search our help in 3 ways: from the Start menu in Windows, from our website, and from within Visual Studio by pressing F1 while coding their applications. Lessons learned: Communication is key when going through so many changes. You also need a champion for your cause - someone in management who is willing to go to bat for you when things get difficult. Good, timely support for the tools you use is also essential.

Lisa Saunders is a Technical Writer/Online Help Developer at Accusoft Pegasus. She has been a technical communicator for more than 15 years and has experience designing and writing documentation for a variety of products and organizations; including technical communication, training documentation, help systems (standalone, web-based and integrated), marketing collateral, best practices, process improvement initiatives, wikis and web content development. Lisa is currently responsible for designing application programming interface (API) help systems for developers that specialize in imaging technology. She uses Innovasys' Document! X and HelpStudio to create and deliver the help systems.

Rachel Samuel has been in the field of technical communication and training for almost eight years and has written documentation and help for the pharmaceutical and healthcare industries. She is a Technical Writer/Online Help Developer with Accusoft Pegasus, which is the largest single source provider of imaging software development kits (SDKs) and image viewers, and caters to various industries. Rachel creates the API, general and demo help for the Accusoft components.

Using MadCap Flare to Single Source Manuals, Help, and Training Guides for a Diverse User Audience

Chris Sullivan, Applied Voice and Speech Technologies • Portland, Oregon

Software Application Description: CallXpress delivers a powerful suite of Unified Communications applications including advanced call processing, voicemail, unified messaging, personal assistant, fax, speech and notification capabilities to help businesses become more productive. For more information about AVST's products visit the company's website at www.avst.com.

We had documentation content spread across numerous help authoring applications, such as RoboHelp and FrameMaker, in order to produce both manuals and online help. We migrated a good portion of it over to Flare and now single-source the manuals and online help from one content source. We are now repurposing much of the same content for our training guides. Since Flare functions at the topic-level, we can drag and drop chunks of content into multiple tables of contents for varying projects. Not only does this process save us a great deal of time and money, it also increases our accuracy: we update the content in only one place instead of several. The content is also used more consistently by more people (end-users, technicians, students, etc.), which allows us to have a tighter feedback loop with our audiences, ensuring that comments and criticisms are dealt with more rapidly.

Currently Director of Training and Documentation for AVST, Chris Sullivan has over a decade of training and documentation experience crossing three vertical industries: telecommunications, medical software, and supply chain. He has successfully morphed the training departments for three companies from strictly in-person to e-learning, and he has single-sourced the documentation sets of two companies, saving hundreds of thousands of dollars in redundant effort.

Using "Single-authoring" to Develop Documentation for Similar APIs in 3 Different Programming Languages

Edward Marshall, Marshall Documentation Consulting • Shirley, Massachusetts

The Tervela Client API documentation provides information to application developers who need to develop, configure, and run Tervela Client Applications to publish and subscribe to high-volume messages such as a NYSE daily feed. Ed had to provide both reference and conceptual information for 3 similar but not identical APIs in 3 different programming languages. The APIs were not only cross-platform but required very different tools to produce the commonly-used formats for the information sets. Ed learned and used tools commonly used by developers including Javadoc and Sun NetBeans IDE / Eclipse to produce the Javadoc output and Microsoft Visual C# / Microsoft Sandcastle to produce a compiled help file (the expected format of information sets for Java / C#); in addition to other tools to run custom build scripts on Linux machines from a Windows PC. The information sets for all 3 APIs provided both reference information and conceptual information, such as introductory information on new features, flowcharts, and extensive hyperlinks / cross-references to relevant sections in the documentation. Conceptual information was provided by creating a “Getting Started Guide” for the C# API from the existing C API Reference Manual and an extensive overview topic in the Javadocs. Ed became adept at adept at “single-authoring” instead of “single-sourcing”. He learned effective and accurate ways to reuse the information for the 3 APIs to produce complete reference and easily navigable conceptual information for each API despite the challenges of using different tools for each API and cross-platform issues.

Ed Marshall is an independent consultant technical writer and the sole proprietor of Marshall Documentation Consulting, with over 22 years in technical writing. He specializes in developer documentation such as APIs (application programming interfaces) / SDKs (software developer’s kits) / Web Services products, etc. Over his career, Ed has developed expertise in using tools to "let the computer do the work," such as advanced tools for editing files, comparing files, and searching / replacing text in files.

Improving Support for Multiple Web-based UA Deliverables and Translations Using Author-it

Cindy Stephens, RWD Technologies • Baltimore, Maryland

RWD Technologies is a leading provider of human and operational performance improvement solutions that help employers maximize the return on their investments in people, processes, technology, knowledge, and customers. Since 1988, RWD has helped thousands of clients globally to enhance organizational productivity through its broad range of integrated products and services.

RWD's leading product is RWD uPerform®, an authoring and content management tool that lets large and small organizations create and deliver targeted, high-quality learning content and information to employees. RWD uPerform® supports standard enterprise applications and Microsoft Windows and web-based applications. Your content authors and subject matter experts can create and maintain your library of materials, while your employees have direct access not only to the individuals who created the data, but also to their colleagues working with the same materials.

Our project began four years ago with three user manuals documenting our client/server application, RWD uPerform, which is used to create and manage help content for enterprise systems. Since that time, we’ve expanded to include an eLearning and student guide editor, a smaller Express version, various supported database applications, and several ways to integrate context-sensitive help with our server application. Our need to turn over projects and translations quickly prompted us to move to Author-it, which has allowed us to better manage and search an extensive topic library, and allows us to reuse content on the fly. We are able to see entire books at a glance, create templates that drive our output types, and decrease the amount of formatting and editing required during review, as well as decrease the amount of time spent authoring.

As our software suite continues to grow, Author-it allows us to create and manage new manuals by moving existing content into new, function-specific manuals. This allows us to provide focused documentation to our end users. Last but not least, our switch to Author-it has allowed us to build more than two weeks into our three-month production schedule that we did not have before. The greatest achievement? We are able to create accurate, user-focused documentation and translated content to our customers faster and better. The lesson learned? Why didn't we do it sooner!

My work as a technical writer at RWD includes project planning, assessment, content creation, and presentation spanning a wide range of media from print to web to hosting seminars that vary in topics from software usage to professional writing. I am schooled in English literature and contemporary American poetry, and my interests include fitness, music, and French cuisine. I live in Baltimore, MD.

Minimalist Indexing for Maximum Help - The AutoCAD Index Redesign Project

Jan Wright, Wright Information Indexing Services • Sandia Park, New Mexico

The AutoCAD online documentation contains a user guide, command reference, drivers and peripherals guide, and a customization guide, and weighs in at over a million words. Prior to index redesign, the merged index was 21,450 lines in length, and user complaints were frequent. For the AutoCAD 2009 and 2010 projects, the Help indexing was redesigned to focus on best topics for users and to complement search.

• Challenges: Reduce print-phrased and -oriented indexing into online-oriented indexing, reduce line count for better user access and lower translation costs, reduce user complaints, and transform legacy indexing into XML compliancy.
• Streamlining, or "let search be search" Exhaustively detailed indexing was discontinued, allowing search to be used for immediate and unique terms. The index leads to the best or most fundamental topics when search results are not precise. The index adds browsability and overviews, and guides users to correct terminology.
• Navigation: In-topic navigational structures, overview topics, and menu topics allow index streamlining. The XML structure automatically populates topics with related links and navigational features, allowing the user to follow the scent of information from the overviews to details.
• Standards: XML-based indexing standards were developed for each category of topic, type of entry, placement, and indexing processes. Indexing guidelines were developed and will be available at the Showcase. Legacy coding artifacts were removed, allowing reuse in future XML tools.
• Tools: Structured Frame, IXGen, Emdex, Excel, and the inhouse help compiler and content management systems. Emdex aided in XML typing of entries, and provided on-the-fly views of a file’s indexing.

Results: Index length dropped to 9,150 lines, and the concise index interface no longer overwhelmed the user. Important topics stand out and are easily chosen. Most entries have just one topic hit, and few have more than two. Before and after screenshot comparisons demonstrate the increase in usability. User reactions for the documentation set are tracked by direct feedback links at the bottom of each help topic. Complaints about the index have fallen off dramatically since the implementation of the minimalist approach, and are now mostly confined to issues submitted from the previous non-streamlined editions, or missing content in the topics linked to by the index.

Jan Wright is an indexer and taxonomist who has been working with documentation since 1991, specializing in help indexing, single sourcing, embedded indexing, tagging, metadata, taxonomies and technical subject matter. Her client list includes Autodesk, Microsoft, Visio, Apple, and other companies. In 2009, she earned the ASI/H.W. Wilson Award for Excellence in Indexing for her index to Real World Adobe InDesign CS3, by Olav Martin Kvern and David Blatner, the first time the award had been presented to a technical manual. Last year, she created the first “virtual coffee shop” for indexers, the Indexers Network at indexing.ning.com. She teaches basic indexing for UC Berkeley, and has a Masters degree in Library Science. Her website, www.wrightinformation.com, exhibits a variety of indexing and tagging techniques.

Using MadCap Flare and Mimic to Create Context-sensitive WebHelp and Interactive Tutorials in Support of a Flash-based Flex Application

Alicia Brown, Sabre Holdings • Southlake, Texas

As a world leader in the travel marketplace, Sabre Holdings merchandises and retails travel products and provides distribution and technology solutions for the travel industry. Sabre Holdings supports travelers, travel agents, corporations and travel suppliers around the world through its three companies: Travelocity, Sabre Travel Network, and Sabre Airline Solutions. www.sabre-holdings.com.

The help system that we are showcasing was developed for the SabreSonic Sell Branded Fares Shopping application. This application allows airline users to differentiate their services by grouping fares into fare families (brands), which gives consumers the opportunity to pay for the services they most value.

The Branded Fares help project is a context-sensitive WebHelp that is hooked up to a flash-based Flex application. Flex is an open source development language that creates a unique set of challenges for online help developers. Flex applications are similar to movies, and they usually only have one URL. In our project, we encountered the following obstacles:

• How do we hook up our files in a flash environment?
• Where do we have our help link and what does it look like in this new type of application?
• How do we allow users to access help content during every process they perform? (Some screens become inactive during different user interactions).

By working closely with our development teams in Poland we were able to overcome our obstacles by adding a button at the toolbar level and a context-sensitive button on the popup pages within the flow of the application. This allows our users to access help content when the background toolbar is unavailable in the editing or creation process of a branded fares program. From this project we learned the following: integration with development teams ensures success, always keep the user's interaction as the focus, and writer's have to lead the way in demanding new solutions when the existing solutions no longer apply.

Our help system was created with Madcap Flare and our interactive tutorials were created with Madcap Mimic. The tutorials (located in the help to supplement the more complex procedures) allow users to train themselves rather than call into the help desk.

I am a technical writer at Sabre Holdings that works closely with Agile development teams to produce user guides, release notes, and online help. I am a graduate of the University or North Texas with a degree in English and a concentration in Technical writing. I have two small children, and I stay busy reading science magazines and historical novels.

Developing eLearning Courses Using Microsoft SharePoint and InfoPath

Matthew Smith, CorVel Corporation • Portland, Oregon

At CorVel, we are using SharePoint, Microsoft InfoPath and K2 Black Pearl to provide self-paced e-learning and evaluations to assess learners’ mastery of the content and track completion rates and scores. E-learning courses are assigned to our sales staff and enterprise application users to minimize travel needs for training and achieve consistencty. SharePoint supports development, storage and security of content in nearly any format – HTML, PDF, Flash We use InfoPath to develop quizzes. The quiz information is stored in a form library with calculated columns that determine the learners’ score and display the results on a custom Web page (created in SharePoint Designer). InfoPath is a form authoring application, and part of the Microsoft Office suite. We use K2 to drive reporting to managers and administrators concerning completion rates and scores. K2 Black Pearl is a business process and workflow platform that integrates with SharePoint.

Matthew Smith is the Documentation and Training Manager at CorVel Corporation (www.corvel.com), a national provider of workers' compensation claims management solutions. Matthew has worked in the technical communications field for over 10 years. Matthew is also organist and choir director at St Stephen's Episcopal Parish in downtown Portland. (www.stst.org).

Working with Author-it and FastHelp to Create Windows Mobile Help in a Single-Source Environment

Sue Heim, PGP Corporation • San Diego, California

More and more organizations are porting their applications to mobile devices. Many writers do not know what is involved in creating on-device help for their applications. This peer showcase will demonstrate how I have been able to continue to use our content management tool (Author-it) with the addition of a another tool (FastHelp) to generate content in both Windows Mobile and PDF formats. PGP Mobile, available only on Windows Mobile platforms, provides much of the same functionality as the client version of PGP Desktop installed on Windows or Mac OS X systems. I'll show how we have been able to continue to single-source content (including reusing content with Author-it Xtend), output that content and then import it into FastHelp to compile into Windows Mobile format. The resulting output is a single HTML file that is displayed on the mobile device.

PGP Mobile is a security tool that uses cryptography to protect data against unauthorized access. PGP Mobile protects yur data by encrypting email individual files, entire data volumes, archives, or directories. Use PGP Mobile to put any combination of files and folders into an encrypted, compressed package for easy distribution or backup. Finally, use PGP Mobile to shred (securely delete) sensitive files—so that no one can retrieve them. All of these functions are also available in our standard PGP Desktop offering that runs on Windows and Mac OS X clients.

The challenges we faced included the ability to easily create the tagged format for the PegHelp format used by mobile devices, the need to minimize costs by reusing existing content. We also needed to be able to quickly create the documentation set for this new platform, ensuring that we had a process that could be easily scaled in the future.

Author-it is a component content management system that allows writers to reuse content, all the way down to the sentence level. All of PGP Corporation's user assistance is published from the Author-it database. For the PGP Mobile project, we had the requirement to publish release notes, a user's guide, an administrator's guide, and on-device help. In order to provide on-device help, we used FastHelp to automatically create the tagged HTML file that renders correctly on a Windows Mobile device. We could take output from Author-it that was single-sourced from the user's guide, and import it into FastHelp. Because we also use Author-it Xtend, we could easily reuse smaller fragments and thereby reduce localization costs (although at this time, PGP Mobile is provided only in English).

PGP Corporation, a global security software company, is the leader in email and data encryption. Based on a unified key management and policy infrastructure, the PGP® Encryption Platform offers the broadest set of integrated applications for enterprise data security. PGP platform-enabled applications allow organizations to meet current needs and expand as security requirements evolve for email, laptops, desktops, instant messaging, PDAs, network storage, FTP and bulk data transfers, and backups.

PGP solutions are used by more than 30,000 enterprises, businesses, and governments worldwide, including 94 percent of the Fortune® 100 and 76 percent of Germany’s DAX index. As a result, PGP Corporation has earned a global reputation for innovative, standards-based, and trusted solutions. PGP solutions help protect confidential information, secure customer data, achieve regulatory and audit compliance, and safeguard companies’ brands and reputations.

Sue Heim has been a technical writer and online help author for 20 years, and a freelance indexer for over 10 years. She is currently employed full-time by PGP Corporation as Lead Technical Writer for the PGP Desktop/Core documentation team. Sue has previously presented at WritersUA and various STC chapters, and has participated in the peer showcase the last two years. A long-time user of Author-it, she is excited to share how Author-it Xtend can help solve linguistic issues and ensure consistency no matter what product you are documenting.

Examples of Project Collaboration Using Google Wave

Char James-Tanny, JTF Associates, Inc. • Lynn, Massachusetts

Google Wave. It started with a (really long) introductory video in May 2009, which got lots of people talking. Then Google slowly started releasing invitations, which was followed by frantic requests for more. But now whenever someone mentions "Google Wave", people raise their eyebrows and shrug their shoulders. Is it already over?

It's not. Google Wave is still going strong, although I haven't seen as much adoption as I expected in user assistance. But I've seen all sorts of waves: ones that mimicked email lists, ones for general discussions, even ones for vacation recaps (with pictures and videos). And I've been using Google Wave for project management (mostly personal), outlines, conference sessions, and school papers.

The bonus with Google Wave for me is that, unlike Google Docs or wikis (which also allow for collaboration), Google Wave includes a playback feature that lets you see what changes were made and who made them. I don't have to compare historical versions to see what changes got made; I can just play the wave back from the beginning.

I'll be demonstrating a variety of waves during this year's Peer Showcase, including some created by others that I've found to be very creative and informative.

Be sure to attend Adam Lasnik's session Google Wave and User Assistance following the Peer Showcase.

Char James-Tanny is president of JTF Associates, Inc. and has thirty years of experience as a technical communicator. She speaks around the world on topics including Help authoring concepts and tools, social media, web standards, collaboration, and technology. Char is an Author-it Certified Consultant, a 2010 Microsoft Help MVP, and the secretary of the Society for Technical Communication.

Easing Customers Through the Transition to the Microsoft Office Ribbon Guides Using Interactive Web-based Tools

Gwyneth Williams Cassazza, Microsoft Corporation • Redmond, WA

With the Office 2007 product release, Microsoft introduced a radically different user interface. Instead of the menus and toolbars used in previous versions, Office 2007 uses the Ribbon - a visually rich, flexible user interface that exposes features in a way that was impossible to do with the earlier menu and toolbar system. Early customer feedback showed that a significant number of customers were concerned about the learning curve associated with making the transition to such a different-looking UI. The Office Content Publishing team (Office User Assistance) worked with the Office User Experience team (part of the Office development team) and a third-party vendor to develop a set of interactive tools whose aim is to help customers learn the new user interface by leveraging their knowledge of the old menus and toolbars. For the Office 2007 project, we created a solution using Adobe Flash. For Office 2010 (and the V2 of these tools) we'll be using Microsoft Silverlight 3. Key features of the solution include the following:

• Customers leverage their knowledge of the old to learn the new
• Old commands and buttons are mapped to the new user interface without making the volume of information seem overwhelming
• We were able to iterate on the basic design used for Word, Excel, and PowerPoint and build it out to accommodate more complex guides for Outlook and Access

The tools are available on the Office Online Web site: http://office.microsoft.com/en-us/training/HA102295841033.aspx

Gwyneth Williams Cassazza is a senior technical writer in the Office Content Publishing group at Microsoft. She started at Microsoft 18 years ago in Product Support Services where she edited articles for the Microsoft Knowledge Base. Since then, she's held a variety of writing and editing positions, most recently working on content for the Office Online Web site. Her current focus is on content that supports customers who are transitioning to the current version Office.

Using RoboHelp and GUIDDesign Studio to Create a Tabbed Help Interface for Accessing Multiple Information Types

Mike Sundstrom, Harley-Davidson Dealer Systems • Valley View, OH

This Help project involves a proprietary software application for Harley-Davidson dealerships. The focus of the project was to make accessing a variety of information types simpler and more intuitive for the end-user, while at the same time keeping development simple and straight-forward. We don't have the resources for any special scripting or coding and we didn't want to learn any new or special authoring tools. The solution we implemented provides context help at the window level, with a tabbed layout to provide access to the five types of information we identified as most useful:

• How to perform specific tasks
• What a particular field represents, or what a particular control does
• What has changed from the old system, or in recent updates
• Provide specific tips or notes about important features and functions
• Provide standard overview and conceptual information

Clicking any of the tabs or Topic Links takes the user directly to the types of information identified above, reducing the confusion typically caused by jumping from topic-to-topic in a standard help system, and they can get to the most common types of information they need with 2-3 clicks. The project was fairly easy to implement using a standard Help Authoring Tool (RoboHelp). The tabs themselves are simply images, created with GUIDesignStudio. You insert the tab images appropriate for a given context screen. A link is then created for each tab image to display that topic. User feedback has been very positive.

I have been involved in a variety of documentation projects at Harley-Davidson Dealer Systems for 15 years, creating the first printed manuals for our original DOS system, implementing WinHelp and PDF user manuals for our first Windows system, and developing the Help system for our current software. During my tenure at HDDS I have also been a field installer/trainer, support specialist, and also participated in a business analyst role in software development.

A Demonstration of an XML-based Documentation Syntax from the Gnome Documentation Team Called "Mallard"

Shaun McCance, Syllogist.net and Jim Campbell, Ubuntu documentation team

The Gnome documentation team is a team of volunteer user assistance writers, developers, and translators who create and distribute the help systems that are used by hundreds of thousands of Linux users around the world. Relying on a small group of volunteer contributors, many of whom have no prior technical writing experience, has posed several challenges to the team. The most recent and successful response to these challenges has been the development of a new XML-based documentation syntax called Mallard. Mallard is under active development, and is currently being used in the production user help for several Gnome- and Xfce-based applications. Mallard-based help can be displayed natively within the Yelp help browser, or via output to HTML. Outputs to PDF are possible via XSLT transformations.

The project was conceived in response to the difficulties that DocBook, the most commonly used open-source XML-documentation markup, was presenting to help authors and developers. For budding volunteer writers, DocBook isn't always easy to learn. Although everything in DocBook (and, similarly, DITA) is there because someone finds it useful, when trying to teach volunteer community members how to write, the size and complexity of the language frequently gets in the way.

Additionally, for Linux distributors and OEMs, trying to integrate custom help content into a set of DocBook documentation is cumbersome. Linking between the original content and OEM- or distributor-specific content frequently requires modifications of the original DocBook source documentation. Thus, any linking between the original and custom documentation sets is clumsy or non-existent.

Finally, DocBook's structural emphasis on writing books or articles did not natively suit the style of topic-based help that the Gnome help developers knew to be effective in assisting users.

Mallard addresses these challenges by providing a simple but comprehensive XML syntax that is designed expressly to fit the needs of end-user help. For example, Mallard contains only 15 block elements, designed to support the most commonly used features. Because Mallard is defined with an extensible RELAX NG schema, vendors can add more specific functionality without adding complexity to the base language.

Mallard also provides extensive automatic linking between related pages in a document. Any custom-developed OEM- or distributor-specific content can easily be integrated into the original Gnome-based documentation with little or no modification of the original sources. Automatic linking is unique to Mallard, and it cleanly addresses a problem that is common in open source and other community documentation efforts.

Mallard is also expressly topic-focused in structure, and encourages writers to write their documentation in ways that help users fix specific problems. Each document is made up of independent pages, and special pages called guide pages help the reader navigate.

Because Gnome officially supports more than 50 languages, it was important that Mallard support localization as well as possible. Mallard is designed to work well with the existing documentation translation tools used in Gnome, and to overcome many of the difficulties Gnome faced in translating DocBook-based documents. The Mallard specification contains detailed conformance notes for the W3C Internationalization and Localization Markup Requirements.

Shaun McCance has over eight years of experience as a writer, programmer, and community leader. A well-known open source documentation leader, he spearheads the Gnome documentation team and maintains many of the programs that make Gnome documentation work, including the help viewer application and the documentation build tools used throughout Gnome.

Jim Campbell has been a member of the Ubuntu documentation team since 2007, and leads the documentation efforts for a light-weight Ubuntu derivative, Xubuntu. Employed as an HRIS Implementation consultant by day, Jim writes user assistance to keep his writing chops sharp.

Using Flare to Develop Context-sensitive Web-based Help for an OS-independent Network Monitoring Application

Patrick Calnan, N-able Technologies • Ottawa, Ontario

N-able Technologies produces award-winning remote network monitoring and system management software that allows you to manage multiple networks and sites from a single interface. N-central, the company's flagship product, allows you to monitor every desktop, server and device in your network as well as controlling any device anytime, anywhere. Accessed through a web browser (IE or Firefox), the N-central server application itself is O/S-independent while supporting agents and probes on Windows, Linux, and Mac OS devices.

In 2007, however, N-able's online help lagged behind its user interface in terms of delivery and functionality. When I was first hired by N-able at that time, I was the junior writer and entering into an environment where the documentation tools and processes hadn't been revised in years.

Challenges Faced

N-able's applications were but the online help produced for them suffered serious problems. Generated from Adobe FrameMaker source files using Quadralay WebWorks to convert them to HTML format, significant manual effort was required both before and after the conversion in order to ensure proper context-sensitive integration. The conversion to HTML was unable to maintain the context-sensitive reference links between the UI and the online help which meant that manual code revisions had to be made to insert the correct topic IDs. And even after hours of editing, the completed HTML help lacked in functionality as it did not use modern navigational tools such as an integrated search feature.

Convinced that change was needed, I immediately began lobbying for a new documentation tool as well as an overhaul of the way documentation was produced. Instead of following processes based on a print model, we needed to adopt Web-oriented procedures so that we could design and manage our content to be accessed through a browser. Management agreed and N-able moved from producing HTML help that was included with the application to fully-featured, hosted Web help that has won fan support all across the continent. Madcap Flare was selected for a new documentation tool because of the sophisticated tools it provided to produce feature-rich Web help as well as the flexibility of its open architecture. The open architecture proved to be especially valuable when a client requested customization of the online help which was easily facilitated using in-house HTML expertise.

While a few dissonant notes were heard along the way due to an ill-conceived attempt to deploy Web help through a SharePoint document library, the migration has proven to be highly successful. Madcap Flare and the Web help format have significantly decreased the amount of time writers spend on manual editing. As a result, N-able's documentation team can now focus more time and energy working directly with content. In addition, integrated search plus improved navigational features have made N-able's online help a big hit with their customers.

Patrick Calnan has worked in information technology for 22 years, 14 of which have been spent in technical documentation. Experienced in Madcap Flare, Adobe RoboHelp and Adobe FrameMaker, he has worked for both large and small companies in telecommunications, network security, collaborative groupware, and browser-based applications. He is now the Documentation Team Leader/Senior Technical Writer for N-able Technologies based out of Ottawa, Ontario, Canada.

Installing the Google Chrome Operating System on a Netbook

Joe Welinske, WritersUA • Vashon, WA

General geekiness found me trying to get the Chrome OS running. It took quite a bit of time to work through all the resources including some conflicting instructions and bad software. It all worked out though and I now have the OS running on a netbook. This demo shows off the results and describes what was involved in getting it done.

If you're not familiar with the Chrome OS you can find the official Google pitch here: http://googleblog.blogspot.com/2009/07/introducing-google-chrome-os.html. There have also been numerous reviews in the tech trade press.

Basically this is Google's attempt to develop a small-footprint control system for netbooks running web-based apps. The core plumbing is Linux and the UI is a variant of the Chrome browser. Whether or not this will find large-scale mindshare won't be determined for quite awhile. The official release will probably be a year from now. But it is an interesting concept and I wanted to get my arms around it. If it does become popular then it will be something that user assistance professionals will need to understand in order to effectively support their apps.

The two major elements are the device hardware and the Chrome OS software.

The pre-release version of Chrome OS has a lot of hardware dependencies. So I did some web research to pick a device on which the OS has been successfully installed. There were a number of candidates. I picked the Asus Eee PC Seashell because it met the requirements and also looked like a nice netbook.

The netbook comes with Windows 7 installed. In order to use the Chrome OS you need to boot from a USB flash drive that has an image of the software on it. The details are described in a blog post.

The first thing to appear is the Chrome browser. The same browser you have on Windows or Mac. The OS doesn't automatically recognize your wifi. A small icon in the top right corner of the screen has a wifi menu. Click that and select your network. I also tested out my ethernet cable and that worked fine. Once that was done I could begin browsing the web.

There is a page that operates as an application dashboard. You can see a screen capture on the Sierra web page. A Chrome icon in the top left corner of the screen launches that page. From there I launched Facebook, Google Docs, etc and put in my logons for each. I couldn't change or add any items to the control panel. I assume that will change. For unlisted applications, like LinkedIn, I launched them in the browser and set bookmarks.

There was an important OS feature that you could test - Cut and Paste. I was able to cut and paste between the various web apps without a problem. While we take this for granted on Windows, Mac, etc, that is the type of behavior that you need an OS for.

Another important behavior is printing. This apparently isn't supported right now. I tried using the print commands in the various apps. Mostly I received error messages. In Gmail the only choice was Print to File. I didn't really expect there to be support for explicit printers. That will be a difficult proposition for Google, I think. But probably a necessary one.

You can play with the Chrome OS / netbook during the Showcase.

Joe Welinske is the president of WritersUA, formerly known as WinWriters. WritersUA is a company devoted to providing training and information for user assistance professionals. The WritersUA/WinWriters Conference draws hundreds of attendees each year from around the world to share the latest in user assistance design and implementation. The free content on the WritersUA web site attracts over 20,000 visitors each month. Joe has been involved with software documentation development since 1984. Together with Scott Boggan and David Farkas, Joe authored two editions of the popular and pioneering book Developing Online Help for Windows. He has also taught online Help courses at the University of Washington and UC Santa Cruz. Joe received a B.S. in Industrial Engineering from the University of Illinois in 1981, and a M.S. in Adult Instructional Management from Loyola University in 1987.

Using Story-boarding, Flash, and Gaming Techniques to Improve Interactivity for Online Training

Jennifer Wheeler, MediaPro, Inc. • Bothell, WA

MediaPro has designed several training courses that feature innovative activities such as 1) a learning-based casual game featuring the do's and don'ts of information security; 2) a Flash-based interactivity embedded with videos to teach learners observation and documentation skills while on construction sites; and 3) a whiteboard-style, branching scenario, security game teaching learners how to respond to security threats.

The main challenge we faced during the development of each of these projects was how to convey our concepts in a user-friendly and accurate manner in order to get client buy-in/sign off before Flash development. Text-based storyboards and discussions weren't effective in conveying our vision and the scope of the design. To help overcome this challenge, we used a graphic and text-based storyboarding process in PowerPoint which enables instructional designers to accurately and realistically convey the vision of the activity (click by click) to clients - and also later in the development process to graphic artists and developers. Although storyboarding in this manner eats up more time in beginning of the project, ultimately it saves money as the concept is more clearly presented and client sign-off is more secure, resulting in less changes after Flash development - it is much easier to revise PPTs than it is to re-program a page in Flash.

Our overall takeaways were that we had developed re-usable activitives which we can re-skin and include in future courseware when clients want high interactivity with medium to low budgets; we had figured out an effective and user-friendly method for storyboarding complicated activities; and we had brought some creativity and sound design into corporate training through the use of gaming and video techniques.

Jennifer Wheeler is a Senior Instructional Designer at MediaPro, Inc. Her experience includes working with an array of subject matters and project scopes to write and design interactive and engaging online solutions. Many of her interactions have contributed to courseware receiving awards from organizations such as Brandon Hall, STC, Horizon, Summit, Axiem, and Omni Intermedia.

Producing YouTube Video Training in Support of Robust Tasks for Visio

Harry Miller, Microsoft Corporation • Redmond, WA

A lot of people who have Microsoft Visio installed at work don't use it, or use it only when they need to for a special job. Visio seems complex and technical; people use it for drawing high-tech electrical schematics and detailed architectural plans. I decided I needed to get more people to see how easy it really is to use, and how many uses it has - complex diagrams don't require complex tools! The problem was that few people care about improving their skills if they're already as good as they think they need. So how could I get people to learn when they don't particularly care? The answer I'm experimenting with is to do it with entertainment.

People watch a lot of short, amusing videos - if I could create an educational series and get people hooked on the story, they'd also learn how to increase their Visio skills along the way, and be more willing to read the regular documentation for the details. The main challenges were coming up with a story line that could logically include using Visio to create diagrams in every episode, and figuring out how to create the show without spending any money and while still delivering regular documentation. The story line took a fair bit of thinking, and creating the show took extra hours on the job (but while having fun!). Fortunately, my work group had just invested in some video equipment and software so I didn't need anything we didn't already have. Basically the tools included: A prosumer video camcorder. A few lights.

Adobe Premiere Pro and After Effects for editing. A co-worker with a theater background for acting. We're still thinking about and experimenting with strategies for getting the videos where people can run across them - they are currently hosted on YouTube and a few other video sites. Response has been good from people who find them, and people often comment that they didn't know Visio did that and they should really pull it out and try it again - exactly the response I want! We're still in the process of analysing responses and distilling lessons, but it seems to be a good way to get people started, and once they're interested, they're more likely to dive in to the detailed documentation as needed.

In ten years as a technical communicator, I've seen a shift that I'm happy to help along - moving from documenting technical things to helping people achieve their goals using technology. There's more opportunity now for creativity, and for using what we know about how the brain works to simplify technology for people. The most useful part of my background was learning how fun it is to explore and share!

Developing a Full-color, Printed Getting Started Guide for the HP TouchSmart Computer

Christina Williams, WASSER • Seattle, WA

When deciding to launch the new HP Touchsmart computer, HP wanted to draw more experienced users who would be attracted to the all-in-one design of the product and its interactive touch screen technology. Together with HP, WASSER designed a documentation set, included in the box, that has an upscale look and feel that appeals to savvy, sophisticated users. The use of full color and ample white space throughout the Getting Started Guide gives the feeling of luxury and enhances the usability of the piece. It also allows for text expansion when the documentation in localized into 30 languages, reducing unnecessary reformatting. The new cover design reflects the new computer model by evoking the sweeping motion of touch screen technology while highlighting the sleek form. The guide introduces Touchsmart computer users to the new hardware and software touch-screen components. It was written so that novice users can read it from cover to cover, relying on the detailed step-by-step instructions. Easily identifiable sections, a detailed TOC, and a comprehensive index allow for experienced owners to use the guide as a reference for individual topics. Use of prominent visual elements throughout, such as photographs, line drawings, and screen shots, adds interest, engages readers, and highlights key points. Supplemental pieces use a stylish grayscale design that complements the full color guide while also keeping overall printing cost low. The "wow" factor of the in-box documentation matches the "wow" factor of the new product without compromising usability.

WASSER is an integrated service company that provides content and digital solution services. Our goal is to create content and user experiences that work. Over the last 14 years, I have worked closely with WASSER clients to develop solutions for their content challenges, resulting in easily understandable content that meets user needs.

Generating an ePub eBook from XML Content with the DITA Open Toolkit

Ray Lloyd, Agfa Graphics • Kessel, Belgium

ePub is a popular format for eBooks which is characterized by reflowable text that can be styled attractively. If you've worked with the Open Toolkit you can also create an ePub eBook from your DITA XML content. In addition, if your content is available in several languages, you can publish all these languages - at no extra cost for DTP work.

I learned about structured authoring and DITA XML in an effort to reduce the translation costs of technical documentation. Producing documentation in several languages usually involves great effort for reformatting each language, even in situations where most of the text has already been translated. Content written and translated in a validated environment can reduce these costs drastically. This is also the case for ePub eBooks generated from structured content. Once your output is set up for an eBook with a particular styling, you can reuse the design for all your languages.

In this showcase you can see how an ePub eBook is generated with the Open Toolkit from DITA XML content with basic customized transforms and CSS style sheets, how the XML content files are translated in a DITA-aware translation memory tool and used to generate the translated ePub eBook just like you made the original language.

Ray Lloyd holds a degree in translation studies and has extensive experience in authoring, translation and publishing processes. He's interested in eliminating the barriers formed by conversions normally involved in multilingual processes. He's based in Flanders, Belgium.

An Unconventional Way to Create Software Videos

Scott Prentice, Leximation, Inc. • San Rafael, CA

It's been my goal to create YouTube videos to present my various FrameMaker plugins for informational, training, and marketing purposes. Over the years I've tried various methods, but never found anything that really worked for me. I quickly found that I was unable to record both voice and screen for more than a few minutes without flubbing something, and realized that the best approach would be to record pieces of the video, then record voiceovers and put it all together for a reasonable presentation. I didn't expect perfection, but wanted it to be polished enough that the viewer could focus on the content without being too distracted by the technology (or my inability to use it).

To accomplish this, I was going to need a screen recording application and an application that let me assemble the video while recording voiceovers to describe what's going on. There are a number of screen recording applications out there, some work better than others, but they all seemed to do a decent job of capturing the video. There are fewer options for video editing software (at least for a reasonable price). Where I had a difficult time was getting the recording and editing software to play nicely together, largely due to codec issues. For someone familiar with these issues, this may not be a serious problem, but for me it was a bit of a showstopper.

I've been in the process of moving my Windows PC based operations to the Mac, running Windows in VMWare Fusion as needed. As is the case with much Apple software, I realized that iMovie was a really nice and simple video editing application, and it exports to a YouTube accepted video format. I found a nice (and cheap) video recording application called iShowU HD (www.shinywhitebox.com). With these tools I'm able to record FrameMaker and other Windows application activity, then complete the video editing and post-production in iMovie, and finally upload directly to YouTube.

I don't claim to be an expert in this field, and my approach may not really be the "best" way to accomplish this task, but I've found that I can sit down and create a decent and useful (hopefully) video within a day's time. It works for me!

Scott Prentice is the President of Leximation, Inc. and has been working in the technical publications field since 1991. His work focuses on custom online help development, FrameMaker (plugin and structure application) development, as well as custom web application development. He has been involved with DITA for many years and created DITA-FMx, an enhanced DITA authoring and publishing environment for FrameMaker. Scott coined the term "AIR Help" after learning about Adobe's new AIR technology.

Using HelpStudio and Document!X to Develop Visual Studio Help and API Documentation

Kim Nathans, GrapeCity, inc. • Galloway, OH

Data Dynamics Analysis began life with a help file written by the project manager and developers. The project deliverables included Visual Studio integrated help, online help, and a printable PDF user guide. The content consisted of a handful of "walkthroughs" which were jam-packed with a variety of information and required about twenty clicks to scroll through, and a class library (API documentation with developer comments from XML).

The challenges I faced with this project were the fact that the original project manager had left the company, and that the developers were all in Russia. With time zone differences and sometimes interesting language challenges, this could have been a daunting task without the support of the new project manager.

After trying out RoboHelp at Honda, I was happy to return to the familiar Innovasys HelpStudio and Document!X tools. Since I planned to scrap most of the original project anyway, I decided to start with a clean, new project and take advantage of all of the new bells and whistles offered by HelpStudio 3 and Document!X 5. Innovasys was really my only choice in tools, because they have always offered excellent support for Visual Studio component help, and make it easy to integrate developer comments into API documentation.

I delivered a complete user guide within five months, with all of the deliverables. There is still a lot that I would like to add to this project that I have relegated to maintenance tasks. For example, the scope of the project did not allow time to edit the developer comments, but I will chip away at this task in the future. While working on this project, I learned the value of asking questions well in advance of when you need answers. Most of the team was in Russia, and my questions were generally misunderstood the first time around, but I can see the value of this practice regardless of the team. I also learned to research the history of features through resolved bugs, which revealed more real-world answers than the more polished wiki articles that contained well-thought-out, coherent plans that were later abandoned.

After Kim Landis Nathans ran out of things to do as a Japanese "office lady," she trained as a developer, and entered the software industry in tech support. There, she was lucky to have her aptitude for writing recognized. She has been happily tech writing for seven years, and broadened her horizons with gigs at vSync (EDI software) and Honda of America (3D visualization software) before returning to Data Dynamics, now owned by GrapeCity, inc.