Notes from 48th International STC Conference
Chicago, Illinois, May 13-16, 2001

Authoring in a Single-Source Environment

JoAnn T. Hackos
ComTech

JoAnn Hackos is an internationally known expert, multiply published author, and successful entrepreneur in technical communication, particularly electronic publishing and project management. Her firm is ComTech.

Session Description: This session addressed techniques for effective reuse of content in multiple deliverables.

• JoAnn began by recounting a story about how she once actually fell asleep while lecturing a class. "It's really bad when you start boring yourself," she allowed. She promised not to demonstrate that technique at this session!
• No amount of technology will ever change the core skills of effective authorship. However, it can make a vast difference in cost-effective creation and dissemination of deliverable documents.
• The old paradigm: one author, one book. Author had total responsibility for design, content, format, editing, and publishing.
• After total chaos in the production of her first book, Managing Your Documentation Projects, Hackos resolved always to maintain total control of production in all future publications. She now sends an unchangeable postscript file of final galleys to her publisher so they can't mess up the final production.
• The dilemma: Although one-book authorship is easy to manage, has lots of personal satisfaction, provides end-to-end control, and allows personal responsibility, it also has significant drawbacks: it is difficult to reuse the information, it is expensive to maintain consistency, it is expensive to translate, and it entails too many responsibilities.
• Use of synonyms plays hell with translation. Despite repetitiveness, you have to use one term for one thing or one concept throughout the document.
• Collaborative authoring is a necessity in a single-source environment. Collaborative authoring allows cost-effective information reuse, specialization through teamwork, focus on users and content, and consistency and adherence to standards.
• Collaborative authoring demands respect and close cooperation, in order to develop a composite style that is transparent to the reader.
• Production should not dominate users and content in book planning, authoring, and publication. It's important, but it is a means to an end, not an end in itself.
• On the flip side of collaborative authoring, it represents a new and different way of working which demands new skills be learned. Consistency and adherence to standards and information coherence within components are critical.
• Most organizations tend to fear that a collaborative project will not be done as well as one that has a single person fully responsible for the entire task.
• A self-managed team will be most effective if it blends a full spectrum of personalities, but only if there is some degree of parity in competence as well as an equitable workshare among its members. For example, in a student teaming project, many of the best students were uncomfortable with teaming, asserting that they felt the process was holding them back, not helping them.
• Owner manuals for several major auto companies are outsourced to one large vendor and are single-sourced. 17,000 different manuals came from one single-sourced database and a process teaming SMEs, editors, and information architects using established templates and stylistic guidelines. Each manual is assembled from the same database, tailored to the individual vehicle.
• XML modules of information are the key building blocks in the single-source publishing process.
• For online reviews, XML files are exported as PDFs.
• Searching for components. Metadata facilitates searching (subject matter details; information type; author, date, revision, version). Metadata structures the contents of the repository to facilitate reuse.
• Metadata is similar to indexing... affixing labels that facilitate electronic access via search engines, etc.
• Searching and reuse. Object-oriented databases are oriented toward rapid retrieval of information for reuse (versus re-creating the information).
• Reusing components.
   
• Large grains are easiest to reuse. Whole chapters and sections are reassembled in many different contexts.
• Smaller grains are more difficult and costly to reuse: e.g., graphics, warnings and cautions, boilerplate text; concepts, procedures, reference information; steps in a procedure. Most expensive instance of reuse was a manual for Army howitzers, which is governed by a spec demanding adherence to complex and exacting requirements.
• "Furthermore, it may be possible for us to add additional metadata tags to the repository by storing the metadata in an external file. We may also be able to write a script to change the attribute values."
• Reusing unstructured text is rarely possible. Idiosyncratic writing and styles complicate reuse.
• Modular writing eschews transitional expressions like "Furthermore," because they are inimical with rapid retrieval and reuse. "Furthermore" implies a number of foregoing points, which are lost if the paragraph is lifted as a stand-alone chunk of information.
• Searching for isolated snippets of reusable text is unlikely to be productive; better to seek larger modules of information that can be reused as is (or with minimal editing).
• Structure authoring enables reuse. Valid XML authoring reinforces rules and encourages consistency. Standard information types and content units encourage uniform structures.
• Subsections can be named according to their content, improving the possibilities for reuse down the road. If subsections are to be reused from within the document, it's important to use XML inside the document. If not, XML might be used only external to the document; in this case, "wrapping" reusable segments is probably the best approach.
• Information reuse demands word-for-word accuracy...otherwise, translation is likely to run into problems. Even subtle differences (e.g., pick up vs pickup) can wreak havoc in reuse of information.
• Structured authoring can be content-based or format-based. If the editor focuses totally on format and mechanics, the content becomes secondary and the user is disserved. On the other hand, if total focus on content causes inconsistencies in format, information reuse is greatly complicated.
• Structured authoring includes topics, components, and effectivity codes.
• IBM has developed the Darwin Information Topic Architecture (DITA).
   
• Topic: concept, procedure, reference
• Organic structure: customer requirements, business requirements, author requirements.
• Can be found at IBM Web site or via search on DITA...a valuable tool...and free!
• If you give your authors a simple, concrete, easy-to-follow format, you will be much more successful than if you try to impose a complex set of codes, etc.
• Effectivity codes are metadata descriptors that label variable components (note that the codes are enclosed in carat brackets):
   
• model=Ford/
• release=1.2/
• industry=commuter/
• country=Spain/
• driver=aggressive/
• Job roles
   
• One writer becomes a subject-matter expert, handling multiple versions of a product or other variables, and multiple information types (concepts, procedures, reference)
• Information architect provides output definitions, content specifications, repository integrity, and release requirements.
• Information designer is another specialist, handling graphic design, Web design, etc.
• Widespread access to the database places strong accountability on authors to provide accurate information...errors are, in essence, public.
• Component guidelines and standards. A purpose statement provides direction.
• Rather than embed design details in a training tutorial, the tutorial is hot-linked to information modules within the overall database that provide the detailed design information.
• Repository management
   
• Write once
• Use in many contexts
• Label for accurate retrieval
• Emphasize usability
• Focus on minimalism
• Additional resources for content management/structured writing
   
• http://www.usabledesign.com for workshops
• http://www.comtech-serv.com for white papers, slides, checklists
• http://www.infomanagementcenter.com for Best Practices newsletter, e-Newsletter subscriptions and membership
• Single-source listserv membership
• The E-Business Workplace: Discovering the Power of Enterprise Portals, by Matthias Vering, Grant Norris, Peter Barth, and James R. Hurley, deals with single-sourced internal databases within companies
• Corporate Portals: Revolutionizing Information Access to Increase Productivity and Drive the Bottom Line, by Heidi Collins, deals with development of single-source databases to increase corporate profit margins.
• Hackos will post ROI data on conversion of databases to single-source format to the STC Web site for the conference.
• The process of converting a large corporfate database to single-source format takes approximately a year, but the long-term payoff is enormous.
• Is there room for creativity within the rather rigid bounds of style and format? Yes... it resides within the information modules, focusing on delivering performance improvement to users. XML is a vehicle to allow cost-effective dissemination of creative information. Examples of creativity within tight structural constraints abound within the arts: witness the sonnet, a classical symphony, light sculptures within translucent plastic.
• The key is to make information readily retrievable and accessible for multipurpose uses: training, marketing, proposals, user documentation.
• What is it like writing in a single-source environment? To the authors, it's much like working off a common server. The database management software is essentially superimposed over the database, but the authors are basically working with modules of information.