The Technical Publications team at Sybase, Inc. maintains many thousands of pages of user documentation and online help topics for a diverse set of software products. Writing teams work in nine locations around the globe; a given project often involves writers from multiple locations. To achieve greater efficiency, increase opportunities for reuse, and improve user experience, the department is moving to the Darwin Information Typing Architecture (DITA) from a variety of source formats. Early adopters realized the need for more detailed information models for several types of content than required by the DITA standard. This chapter discusses why models are a critical component to successful collaborative writing, especially for topic-oriented content. It then describes the collaborative processes and tools by which Sybase® Technical Publications team members propose, evaluate, develop, test, and enforce new content models, challenges encountered, and key success factors.
TopIntroduction
It is 4:00 PM in Paris, 3:00 PM in London, 10:00 AM in Boston and Waterloo, 8:00 AM in Denver, 7:00 AM in California, and 11:00 PM in Singapore. The Technical Publications (Tech Pubs) team for Sybase Proposed Product—information architect, authors, editor, build expert, and project lead—gather by phone and Web meeting to discuss how they will develop content for their new project. The Tech Pubs director has announced that, to facilitate content reuse and reduce localization costs, the team will be adopting the DITA architecture for this highly visible project. The information architect notes that the new product will share some of his existing several-thousand-page doc set; he also has found some redundant content and plans to apply minimalist principles and DITA’s topic-oriented approach to make the information more effective. The authors in Singapore, California, and Colorado say they are pleased about learning the DITA standard, but they also are very nervous about the major learning curve it involves. The editor would like to see greater consistency among installation guides for different products. The build expert has learned that the product requires Eclipse output for CD, Web, and dynamic product help, two types of Microsoft® help, as well as PDF files. And, as if things were not exciting enough, the project lead warns everyone that the agile development process the company is adopting means they no longer have 12 or 18 months to document a major new release, but instead must deliver customer-ready content for a series of breathtakingly brief 8-week sprints through a long roadmap of new product features.
Sybase Tech Pubs develops user documentation for dozens of products. Our audience is technically sophisticated, including database, system, and security administrators, data and business process modelers, enterprise software developers, and mobile business application developers. Sybase technical writers must be comfortable not only with writing text and using authoring tools, but also with testing the software they document—creating databases, developing applications, performing complex installations. Most Sybase authors have more than 10 years of experience in the industry; many have far more than that.
The information products we deliver also are increasingly complex and diverse. They include not only traditional user guides and reference manuals, but an ever-increasing number of online help formats that require greater integration with the product user interface. We still produce PDF files for electronic and printed books, but we also provide HTML, several Microsoft® help formats, and Eclipse®-based information centers delivered in the product user interface (UI), on CD, on the public Website, and by download. (Eclipse® is an open-source integrated software development environment that also supports software and information deployment.) Some content is localized in as many as 10 languages, sometimes with simultaneous delivery of English and translated content.
In the past, writers have developed source content for these multiple delivered formats using a variety of common authoring tools. Much of our legacy content was developed in Structured FrameMaker®, which allows us to do single-sourcing for multichannel publishing (see Chapter 14), but does not readily support the level of content sharing across components and products that we are required now to provide. The ability to reuse content at varying levels of granularity has become critical not only to stretch our resources, but also because the products themselves share components at many levels. Some project teams approached this challenge by using the DocBook standard to manage document structure. But our director was convinced that the new DITA standard was gaining momentum among leaders in the technical writing industry. Driven by changing product requirements and the need for ever greater efficiency, Sybase Tech Pubs has adopted DITA as its standard, and is using a content management system (CMS) to develop and manage a growing repository of DITA content.