1. 1 © 2005 Lenovo Lenovo Non-Confidential Understanding a single sourcing solution Andre’ Evans – Staff Software Engineer September 2006

2. 2 (March 14, 2006) Lenovo Confidential © 2005 Lenovo (Andre’ Evans) (Understanding a Single Source Solution) Overview  What is single sourcing?  Why is single sourcing useful?  How do people single source?  What does a generic single sourcing solution look like?  Developing a single sourcing architecture (Part I) -Choosing an authoring methodology -Choosing an authoring tool -Choosing how to store information -Determine a translatable file format -Choosing how to process information -Deciding how to deliver information

3. 3 (March 14, 2006) Lenovo Confidential © 2005 Lenovo (Andre’ Evans) (Understanding a Single Source Solution) What is single sourcing?  The concept of single sourcing made one its first appearances in STC’s 46 Annual Conference publication in 1999 with four articles attempting to define the term.  The following definitions are attempts to explain the concept of single sourcing: -STC Single Source SIG: Using a single document source to generate multiple types of document outputs; workflows for creating multiple outputs from a document or database source.

4. 4 (March 14, 2006) Lenovo Confidential © 2005 Lenovo (Andre’ Evans) (Understanding a Single Source Solution) What is single sourcing? (continued) -Stewart Florsheim: Two basic distinctions between format and content: Content: Distributing the same content in multiple formats. Content is usually written once, in one particular medium, and then moved into alternative media. Example: Book to Help System Format: Distributing complementary content in the most appropriate medium. Content is designed for and created in the most suitable medium. Example: Printed manual (Informational content) Help system (Instructional content)

5. 5 (March 14, 2006) Lenovo Confidential © 2005 Lenovo (Andre’ Evans) (Understanding a Single Source Solution) What is single sourcing? (continued) -Mark Baker: The single source in a robust single source system is not any one of the outputs that may be created from that source. -Dawn Stevens and Ann Rockely: The ability to write information once and use it in a variety of outputs -Ann Rockley and JoAnn Hackos: Content is contained in a database. Single source information is broken down to the element level (section, paragraph, and sentence). When information is broken down to this level, it is easy to select an element to reuse or repurpose.

6. 6 (March 14, 2006) Lenovo Confidential © 2005 Lenovo (Andre’ Evans) (Understanding a Single Source Solution) What is single sourcing? (continued) -Andre’ Evans: A methodology whereby object-oriented, or topic based, information is contained within a single location and reused in the same or multiple formats; for the same or multiple audiences; for the same or multiple products; for the same or multiple brands.

7. 7 (March 14, 2006) Lenovo Confidential © 2005 Lenovo (Andre’ Evans) (Understanding a Single Source Solution) Why is single sourcing useful?  Typically, single sourcing is a viable option if you: support multiple platforms; support similar products; customize solutions for your customers; support several different audiences; require multiple media outputs; update the information often; translate the information into multiple languages.

8. 8 (March 14, 2006) Lenovo Confidential © 2005 Lenovo (Andre’ Evans) (Understanding a Single Source Solution) Why is single sourcing useful? (continued)  A single sourcing method enables us to achieve: Consistency -Consistent messaging across deliverables -Consistent layout or design of content -Consistent authoring tone -Consistent authoring method

9. 9 (March 14, 2006) Lenovo Confidential © 2005 Lenovo (Andre’ Evans) (Understanding a Single Source Solution) Why is single sourcing useful? (continued)  A single sourcing method enables us to achieve: Efficiency -Decreases opportunity for error (less testing) -Reduces authoring time -Reduces translation costs -Identifies target audience(s) -Segments task-related information -Reduces amount of authoring changes -Increases ability to absorb change

10. 10 (March 14, 2006) Lenovo Confidential © 2005 Lenovo (Andre’ Evans) (Understanding a Single Source Solution) What are ways people single source?  Help to Help and Book to Book -(Articles, topic-based files, object-oriented documentation from one deliverable to a different deliverable of the same medium) PDF to PDF HTML to HTML

11. 11 (March 14, 2006) Lenovo Confidential © 2005 Lenovo (Andre’ Evans) (Understanding a Single Source Solution) What are ways people single source? (continued)  Book to Help (WinHelp, MS HTML Help, Java Help, HTML- based help (four formats), XML-based help (two formats) Converting FrameMaker files to:.CHM (Compiled Help Modules) XHTML DITA XML Windows Help Doc Book XAML

12. 12 (March 14, 2006) Lenovo Confidential © 2005 Lenovo (Andre’ Evans) (Understanding a Single Source Solution) What are ways people single source? (continued) -DITA to deliverable XML files to: PDF HTML XHTML Windows Help Doc Book XAML Note: Converting to HTML, XHTML, and PDF addresses possible Web deliverables

13. 13 (March 14, 2006) Lenovo Confidential © 2005 Lenovo (Andre’ Evans) (Understanding a Single Source Solution) What does a single sourcing solution look like? A generic single sourcing method may look something like this:

14. 14 (March 14, 2006) Lenovo Confidential © 2005 Lenovo (Andre’ Evans) (Understanding a Single Source Solution) Finding a single sourcing architecture  Things to consider when developing a single source solution: -What do I want to accomplish? -What is my authoring methodology? -How is the information I create stored? -What formats will I support? -Do I have translatable file formats? -How is the source information I create processed/transformed to the deliverable(s) I need?

15. 15 (March 14, 2006) Lenovo Confidential © 2005 Lenovo (Andre’ Evans) (Understanding a Single Source Solution) Choosing an authoring methodology  Your authoring methodology becomes increasingly complex as your deliverables and deliverable formats increase.  Types of deliverables include: -Quick Reference Guides -Online User’s Guides -Install Guides -White Papers -CD labels -Flyers -Packaging specifications -Posters -Help systems -Graphical User Interface text -Readmes -Hints and Tips

16. 16 (March 14, 2006) Lenovo Confidential © 2005 Lenovo (Andre’ Evans) (Understanding a Single Source Solution) Choosing an authoring methodology (continued)  Current industry trends are leaning toward using XML and DITA in combination to author information. -XML is code used by the tool -DITA (Darwin Information Typing Architecture) is a methodology used by the authors

17. 17 (March 14, 2006) Lenovo Confidential © 2005 Lenovo (Andre’ Evans) (Understanding a Single Source Solution) Choosing an authoring methodology (continued)  XML is a popular single source code language because: -Its flexibility enables authors to meet shorter schedules -It supports DITA-specialized Document Type Definitions, which define markup rules -Separates fashion from function (format from content)

18. 18 (March 14, 2006) Lenovo Confidential © 2005 Lenovo (Andre’ Evans) (Understanding a Single Source Solution) Choosing an authoring methodology (continued)  A little about DITA -Darwin: Based on principles of inheritance and specialization -Information Typing: Supports topic-based methodologies -Architecture: Structured to support easily extensible vocabulary

19. 19 (March 14, 2006) Lenovo Confidential © 2005 Lenovo (Andre’ Evans) (Understanding a Single Source Solution) Choosing an authoring methodology (continued)  DITA can be broken down into the following articles or topics: -Task -Concept -Reference  Characteristics of a topic: -One subject, signified by its title -Wording that is independent of any other topic -Meaningful when it stands alone

20. 20 (March 14, 2006) Lenovo Confidential © 2005 Lenovo (Andre’ Evans) (Understanding a Single Source Solution) Choosing an authoring methodology (continued)  How to document a task:  Develop a task analysis -Write to support the user’s objectives. -Start with outlining major tasks. -Write task overview topics. -Break larger tasks into smaller tasks. -Link each step in an overview topic to a separate topic that explains it in greater detail.

21. 21 (March 14, 2006) Lenovo Confidential © 2005 Lenovo (Andre’ Evans) (Understanding a Single Source Solution) Choosing an authoring methodology (continued)  How to document a task: -When necessary, provide background information: To place the task in a larger context. To provide an important concept or definition.

22. 22 (March 14, 2006) Lenovo Confidential © 2005 Lenovo (Andre’ Evans) (Understanding a Single Source Solution) Choosing an authoring methodology (continued)  Typically, write tasks first then determine which concepts are key  How to document a concept: -Answer questions like: What is this feature? Why and when do I need it? -Provide definitions to establish context -Move from general to specific -Provide overarching explanations -Use graphics to illustrate an idea.

23. 23 (March 14, 2006) Lenovo Confidential © 2005 Lenovo (Andre’ Evans) (Understanding a Single Source Solution) Choosing an authoring methodology (continued)  How to document a reference file: -Can be complete sentences -Tabular

24. 24 (March 14, 2006) Lenovo Confidential © 2005 Lenovo (Andre’ Evans) (Understanding a Single Source Solution) Choosing an authoring methodology (continued)  A DITA methodology requires: -Chunking content into topics -Chunking design into modules -Chunking processes into modules -A Task.dtd -A Concept.dtd -A Reference.dtd -XSLT transforms that focus on topic types, not document types

25. 25 (March 14, 2006) Lenovo Confidential © 2005 Lenovo (Andre’ Evans) (Understanding a Single Source Solution) Choosing an authoring methodology (continued)  The following guidelines can help you write topic- based documentation that is used when implementing DITA. -This methodology is truly task-oriented information. -Provide enough detailed levels of information. -Make good decisions about what to include and what to leave out. -Provide for complex search and retrieval of information.

26. 26 (March 14, 2006) Lenovo Confidential © 2005 Lenovo (Andre’ Evans) (Understanding a Single Source Solution) Choosing an authoring methodology (continued)  Incorporate minimalist user assistance principles that: -Lets users start immediately on tasks. -Minimizes the amount of reading and passive training. -Includes error recovery activities as part of the instruction. -Makes all learning activities standalone and independent of sequence. -Builds on the users experience. -Document only one way of doing things.

27. 27 (March 14, 2006) Lenovo Confidential © 2005 Lenovo (Andre’ Evans) (Understanding a Single Source Solution) Choosing an authoring methodology (continued)  Possible tools include: -Epic Editor -XMetal

28. 28 (March 14, 2006) Lenovo Confidential © 2005 Lenovo (Andre’ Evans) (Understanding a Single Source Solution) Choosing how to store information  After authoring your topics, you need to store the information.  Typically, this is done in a Content Management System (CMS)  Most industry-standard tools come with a CMS.  Not all CMSs are created equal. An XML database does not have the same functions as some CMSs.  Ensure that the metadata method you choose to use when authoring is accepted by the CMS.

29. 29 (March 14, 2006) Lenovo Confidential © 2005 Lenovo (Andre’ Evans) (Understanding a Single Source Solution) Determine a translatable file format  After you author your topics, research different translation centers.  Compare costs.  How much time to they need before you deliver the files?  Determine if they can translate the files you intend to use.  Are there any tools they can provide so that you can ensure that your files are 100 percent compliant with the translation requirements?

30. 30 (March 14, 2006) Lenovo Confidential © 2005 Lenovo (Andre’ Evans) (Understanding a Single Source Solution) Choosing how to process information  Does my authoring tool have the ability to transform and process the files I have to the deliverables I want?  What DTDs do I need?  Are Schemas better? Why or Why not?  When do I need an FO processor?  When and why would I need one or more XSLTs?

31. 31 (March 14, 2006) Lenovo Confidential © 2005 Lenovo (Andre’ Evans) (Understanding a Single Source Solution) Deciding how to deliver information  Where are my deliverables going to be posted: -On the Web? Internet Intranet -On a CD? -Printed? -Provided to a vendor on a server requiring a specific file format?