Notes from 47th International STC Conference
Orlando, Florida, May 21-24, 2000

All About Single Sourcing

Ann Rockley
The Rockley Group, Inc., in partnership with SingleSource Associates

An Associate Fellow in STC, Rockley has 18 years' experience and an international reputation in the field of online documentation. She is president of the Rockley Group, Inc., and a partner with JoAnn Hackos in SingleSource Associates.

Session Description: This session described single sourcing information for multiple media, multiple types of information, multiple users, and reuse of information for multiple products.

• Presenter has been involved with online documentation since it first hit the industry. She began working with single sourcing via Standard Generalized Markup Language (SGML) about 10 years ago.
• Single sourcing begins with information analysis, and it requires a design for single sourcing.
• What is single sourcing?
   
• One information source (input)
• Multiple methods of delivery (output)
• Structured vs unstructured input: you always do things the same way
• High vs. low control over input
• Multiple media: paper, HELP programs, online, Web-based
• Multiple users
• Multiple versions of information for diverse product lines
• Multiple languages
• Customized documentation
• It's important to be as structured as possible, avoiding tailoring and "tweaking," because any tailoring must be replicated on each subsequent output. For example, formatted items like tables should always be handled the same, as mapped. Individualizing for a specific output media (e.g., changing column width) constitutes tweaking, which would then have to be replicated on each subsequent use.
• Levels of single sourcing
   
• Level 1: Identical content, multiple media. Content is converted into paper, .pdf, HTML, XML.
• Level 2: Static customized content. Author selects from elements to create customized documents.
• Level 3: Dynamic customized content. Users identify required content or user profiles and personalization provides the appropriate information to users.
• Level 4: Electronic performance support systems. These have been prohibitively expensive. They support users in a whole range of roles (information, decision-making, learning).
• Case #1: Major computer manufacturer
   
• Original documents consisted of 2 manuals, 250 pages each, 2 writers
• Single-source solution led to one manual plus differences...saved $1M in translation costs and reduced time to produce a new manual from 3 weeks to 1.
• Case #2: Major printer manufacturer
   
• Original documentation was 8,000 pages.
• Single-source solution reduced page count by 20%, reduced development time by 50%, and saved $500K.
• Case #3: Major retirement fund administrator
   
• Large system: 800 screens, 5,000 fields, 4,000 pages.
• Single-source solution involved context-sensitive Windows Help, Web-based user documentation, and paper-based training materials.
• Rockley quote for the entire job was less than 50% of the quote for just the training materials. Estimated total savings = 60%.
  
• Traditional costs: 6 hours per page of doc, 4 hours per Help topic, 40+ hours per hour of instruction. Single-sourcing substantially reduces all 3.
• Designing for single-sourcing begins with audience analysis.
   
• Detailed audience profiles
• Detailed customer task analysis
• Clear description of customer goals and expectations
• Next is information analysis.
   
• Repetitious info. Note: It's often harder to reengineer an existing database than it is to design a new one.
• Similar topics
• Potential missing information
• Multiple outputs, media
• Multiple audiences
• Then comes information modeling.
   
  • Information can be consistently modeled
  • Information product models
  • Element models (e.g., kitchen Vs bedroom. Most elements are different but some [e.g., a door] are common.)
  • Procedure model: Link to previous procedures (prerequisites, body of procedure, See Also)
  • Enforcing models: XML imposes an underlying document structure.
  • Building block approach: some elements are universal; others don't apply to Help, to user guide, or to training materials.
  • Nesting: Training is at the core; the user guide builds on it; Help builds on that.
  • Example: from retirement fund (designed from scratch with 3 different outputs in mind: training, Help, and user doc).
     
  • Help guide on right
  • User doc on left
  • Pop-up menus required standard use of terms
  • Microsoft Word and RoboHelp are not good single-source applications. They can be made to work, but are not the right solution.
  • User takes the core and chooses which elements he/she wants. Elements aren't really there; instead, they are pointers out into the database.
• Structured writing is critical to successful single sourcing.
   
• Analyze info to determine hot it is best communicated to readers
• Identify common info elements across a documentation set/product line
• Chunk into manageable size elements
• Determine suitable format for each chunk of info
• Group and sequence chunks into related topics
• Present the info in a manner best suited to the information's purpose and to the users' needs.
• Dealing with heterogeneous user base, from novice to expert. Lean toward novice without being patronizing. Nobody is likely to complain about good, simple, clear writing.
• The single-source writer has to spend a lot more time on analysis and writing than a traditional writer, but devotes almost no time to production, whereas that is often a big part of the traditional writer's job.
• Senior writers tend to move into analysis and design, ultimately becoming manager/owner of the process.
• Intermediate writers have excellent writing skills and minimal tool knowledge.
• Production people need excellent tools knowledge, especially conversions.
• Writers should write, producers should produce. It is not cost-effective to tie up writers in the tool skills. They need to focus on information analysis, design, and WRITING!
• Meta tags: a way of attaching information to information. In Framemaker, it's like a conditional attribute. Meta tags are key to single-sourcing's ability to meet various audiences, different software versions, different platforms, and different media. Indexers are very good at meta tags; they are used to categorizing and using lexicon.
• How are authors likely to want information? Users? The answers to these questions drive the Author and User meta tag structures.
• Testing and prototype: A working model, a prototype, processes. This is an extremely important step in the single-sourcing process. It's important not to test just the content or just the structure: BOTH need usability testing.
• Standards: production guides, style guides, models...to help authors write consistently.
• 6 weeks is minimal for testing, longer for huge sites. Six months is about the fastest a single-source solution could possibly be developed and implemented.
• Don't pick a mission-critical product for your maiden flight with single-sourcing! Schedule pressure will cause steps to be skipped, undermining the process and diminishing the results.

Questions and Answers

• An inexpensive solution for single-sourcing is Framemaker Plus with Multimedia, for a limited number of outputs. Microsoft Word is utterly hopeless.
• XML is highly effective for content management; it's much harder without it.
• Review process: Since training is a superset of everything, the key is to get management/technical buy-in on a comprehensive unformatted paper printout of that database. Since the user's guide and online Help are subsets of that database, approval for those is assumed once the overall database is approved.
• Translators have to use Web-based versions of the same tools to translate single-sourced databases.
• Context is critical.
• Role of formal processes such as ISO 9001? Very important. Repeatable processes are key to success with single-sourcing.
• The lever to get management support to impose repeatable processes organization-wide is to prove the cost savings that can be achieved by so doing.
• Writers who are comfortable working with the tools are loath to give up that function and focus on information analysis and writing.
• RoboHelp single-sources identical sources to multiple media; you cannot get below the section level. ForeHelp provides the additional capability.