Creating Reusable Content Using a Single Source for Information

Overview Definition of Reusable Content Examples of Reusable Content Methods for Creating Reusable Content Standards for Writing Reusable Content Pros and Cons of Reusable Content 2 2

Overview Definition of Reusable Content Examples of Reusable Content Methods for Creating Reusable Content Standards for Writing Reusable Content Pros and Cons of Reusable Content 3 3

Definition of Reusable Content Reusable content is used by businesses and organizations so the same information isn’t constantly written over and over Reusable content is stored in a central location to be accessed and used/modified by all parts of an organization

Definition of Reusable Content Reusable content is written and/or compiled by a single person or a team of people Reusable content is maintained in an unformatted master document The content is located in a master document so writers can access to create information products The content is unformatted so it can be styled according to the information product 5 5

Overview Definition of Reusable Content Examples of Reusable Content Methods for Creating Reusable Content Standards for Writing Reusable Content Pros and Cons of Reusable Content 6 6

Examples of Reusable Content Reusable content is a single source of information that can be used in more than one information product and output format Examples of Information Products: User’s guides and setup guides Brochures and advertisements Technician manuals Example: A section of a car manual (such as “Changing Tires” for a particular model is reused in manuals for other car models of the same company and for online help

Examples of Reusable Content Examples of Output Formats: Printed manual in PDF format Online help Web site in HTML code Customer support CD Example: the user’s guide of a software product is available as a printed manual in PDF format, a Web site in HTML format, and as online help 8 8

Examples of Reusable Content (cont.) Figure 1: Chart showing how several departments use content for different information products in different formats Uses: Product name Description Assembly instructions Activation information Technical Writing Department To Create: User’s Guides Uses: Product name Price Description Feature List Single source of information Introduction to Structured Content Management with XML by Kay Ethier and Scott Abel Marketing Department To Create: Brochures Uses: Product name Price Description Contact information Online Content Writing Department To Create: Product Web Page

Overview Definition of Reusable Content Examples of Reusable Content Methods for Reusing Content Modular Content Conditional Text Conversion Tools Structured Content Standards for Writing Reusable Content Pros and Cons of Reusable Content 10 10

Methods for Reusing Content: Modular Content Modular content is written in chunks (or “modules”) of related information so the appropriate modules of content can be reused for different information products Before writing, the various modules of information necessary for all information products are planned Example: Descriptions, procedures, and lists 11 11

Methods for Reusing Content: Modular Content After planning the necessary modules of information, they can be reused in different information products Example: A product description is used in a user’s guide, online help, Web site, and brochure Example: Billing information is used for a Web site only 12 12

Methods for Reusing Content: Modular Content (cont.) Modular content is written so it can stand alone by avoiding references that: Cannot be reused in a different information product Example: The “Changing tires” section in a manual might say “as discussed in the overview” and thus can’t be reused for a quick reference guide that doesn’t have an overview Cannot be arranged in a different sequence Example: References to “see below,” and “the following section” 13 13

Methods for Reusing Content: Conditional Text Conditional text is content tagged/marked as conditional so it appears only in certain renditions of the document (untagged content is used in all renditions) Example: Products A and B use the same warranty information (untagged), except A has a 5 year warranty (tagged conditional for A), and B has a 3 year warranty (tagged conditional for B) Example: A hardcopy user’s guide has a section called “Concepts” whereas the online version does not

Methods for Reusing Content: Conditional Text (cont.) Conditional text is supported by authoring tools such as: Adobe FrameMaker Microsoft Word when used with a plug-in called Live Linx Conditional Text for Word These tools allow you to: Selectively include a piece of text in an output document by using predefined tags Is maintained in one master document from which various information products are made

Methods for Reusing Content: Conversion Tools Conversion tools convert data from one primary source output format into another output format automatically Example: Content written for a hardcopy can be converted to online content Conversion tools define conversion rules based on formatting styles in the primary source Example: A “Body” paragraph tag written in FrameMaker can be converted to “Body” paragraph style in HTML output Example: H1s written in a Microsoft Word document can be converted to topics in Online Help

Methods for Reusing Content: Conversion Tools (cont.) Popular conversion tools: Quadralay WebWorks ePublisher: converts print-based documents in MS Word or Adobe FrameMaker to online help, HTML , or others Doc-To-Help for Word: converts MS Word documents to various online help formats Adobe RoboHelp: converts HTML documents to various online help formats PDF Online: converts PDF to MS Word format or vice-versa for free

Methods for Reusing Content: Structured Content Structured content is information that has been broken down into chunks and labeled with keywords according to hierarchy and then organized in outline form Example: The element “Changing Motor Oil” is labeled with the keyword “section title” and the first step in the procedure is labeled with the keyword “step” The output format of structured content is produced according to styles defined for each keyword

Methods for Reusing Content: Structured Content (cont.) Designing Step-by-Step Instructions Writing quality instructions requires knowledge of the hardware or software, as well as skills in writing. Consider these questions when writing step-by-step instructions: What's the reading level of the user? What is their experience with computers? Reading level of the users Sample text. Experience with computers chapter title list item 1 synopsis list item 2 section title A Paragraph 1A Paragraph 2A section title B Paragraph 1B Paragraph 2B Figure 2: Keywords based on subject matter assigned to various document elements

Methods for Reusing Content: Structured Content (cont.) Chapter Chapter Title Synopsis List Section List Item 2 Section Title A Paragraph 1A Paragraph 2A Section Title B Paragraph 1B Paragraph 2B List Item 1 Speaker notes hint: tree structure Figure 3: Outline representation of labeled modules in a document

Methods for Reusing Content: Structured Content (cont.) The output format of structured content is produced according the style sheet defined for each keyword used in the information product Example: The keyword “Product feature list” could be size 32 in black Arial font for the user’s guide and size 40 in blue Arial font for the brochure

Methods for Reusing Content: Structured Content (cont.) Structured content labeled with keywords Style sheets for each type of output format Software that applies formatting rules in style sheet to content User’s Guide Web Site Help System Figure 4: Flowchart showing how structured content and style sheets come together in a software program to produce different information products 22

Methods for Reusing Content Structured Content Tools Structured content can be reused by using software that supports one or more of the following: Content Management System (CMS) Extensible Markup Language (XML)

Methods for Reusing Content Structured Content Tools: CMS A CMS is a tool that enables users to: Work with a variety of content such as text, graphics, videos, documents, etc. Create and manage content using its own authoring interface or by integrating another third-party tool Store content modules in a database Categorize content modules stored in the database Define the structure and format of an information product using “templates”

Methods for Reusing Content Structured Content Tools: CMS (cont.) Content created and stored in a CMS can be reused to create information products by: Searching for content by category using query features of the database Populating the pre-defined “template” of an information product using the searched content, similar to filling in an outline

Methods for Reusing Content Structured Content Tools: CMS (cont.) Popular CMS based solutions for publishing technical documentation are: Author-it Documentum Technical Publication Solution (TPS)

Methods for Reusing Content Structured Content Tools: XML XML is a mechanism to structure content by: Storing chunks of modular content called “elements” Describing each content module with a keyword like “tag” or “metadata” Assigning “attributes” like “author” or “version” Describing the structure of an information product in a definition file, either a Document Type Definition (DTD) or an XML Schema Describing the format of an information product using style sheets

Methods for Reusing Content Structured Content Tools: XML (cont.) <chapter author=“John Smith”> <chaptertitle>Designing Step-by-Step Instructions</chaptertitle> <synopsis>Writing instructions requires knowledge of the products </synopsis> <list> <item>What's the reading level of the user?</item> <item> What is their experience with computers? </item> </list> <section> <sectiontitle>Reading level of the users</sectiontitle> <para>sample text</para> </section> </chapter> attribute start tag end tag element Figure 4: A document written in XML. The callouts identify an attribute, start and end tags, and an element

Methods for Reusing Content Structured Content Tools: XML (cont.) Structured content in XML can be used to publish multiple information products by: Searching elements using tags or attributes like search for a ‘chapter’ with ‘title’, ‘Designing step by step instructions’ written by ‘author’, ‘John Smith’ search for all chapter titles and synopses, to create a preface chapter Using elements to write within predefined structures Applying formatting from style sheets

Methods for Reusing Content Structured Content Tools: XML (cont.) Popular XML based solutions for authoring and reusing structured content are: Arbortext Xmetal XMLmind Adobe FrameMaker

Overview Definition of Reusable Content Examples of Reusable Content Methods for Creating Reusable Content Standards for Writing Reusable Content Purpose of Established Writing Standards Examples of Established Standards Tips for Writing Reusable Content Pros and Cons of Reusable Content 31 31

Standards for Writing Reusable Content: Purpose of Established Writing Standards Standards are predefined structures and writing guidelines followed within a company or industry to achieve one or more of the following: Regulatory compliance: Medical companies doing business in U.S. must comply with FDA regulations Industry conformance: U.S. military created the first industry content standard (CALS) to make information provided by thousands of its vendors more consistent Information interchange: When companies or groups with common interests use the same standard, it facilitates information sharing or exchange

Standards for Writing Reusable Content: Examples of Established Standards Individual companies usually adopt one of these established writing standards DITA for topic-based documentation http://www.ibm.com/developerworks/xml/library/x-dita1/ DocBook for book-based documentation http://www.oasis-open.org/docbook/ SCORM for e-learning http://www.adlnet.gov/scorm/index.aspx S1000D for military equipment http://www.s1000d.net/ SPL for pharmaceutical labeling http://www.fda.gov/oc/datacouncil/spl.html

Standards for Writing Reusable Content: Tips for Writing Reusable Content Some general advice for writing reusable content is: Set user expectations What information do they need? How will they best get that information? Plan all of the information products you intend to create and the elements they contain Identify the content used Identify the content that can be reused across different information products Determine the best method for reusing content based on the restrictions of the information products you are creating Define a style sheet for each information product 34 34

Overview Definition of Reusable Content Examples of Reusable Content Methods for Creating Reusable Content Standards for Writing Reusable Content Pros and Cons of Reusable Content 35 35

Pros and Cons of Reusable Content: Pros Increases the amount of consistent information in a variety of written material Reduces the time and money spent writing multiple versions of the same content Reduces the volume of content that needs to be written for the different needs of publications Allows writers to quickly pull content from one source instead of regenerating content over and over Reduces translation costs because reusable content needs to be translated only once http://www.peachpit.com/articles/article.aspx?p=29753&seqNum=2

Pros and Cons of Reusable Content: Cons Takes more time and resources for planning Increases up-front work for organizing and composing source documentation Requires new technology and tools for writing, storing, and reusing content Requires at least 50% of the content to be reused across different information products to save time and money in the long run Creating Context Sensitive Help Using Single Sourcing, STC India, Chennai 6th Annual Conference December 2-4, 2004. Debjani Sen and Roger Dearth

References Ament K, (2003). Single sourcing: Building modular documentation. Norwich, NY: William Andrew Publishing. Rockley, A. Fundamental Concepts of Reuse. Retrieved 12/11/08, from Peachpit, Website: http://www.peachpit.com/articles/article.aspx?p=29753&seqNum=2 Self, T. (March 2007). Semantic, Structured Authoring. Retrieved 12/11/08, from HyperWrite Consultancy and Training Website: http://www.hyperwrite.com/Articles/showarticle.aspx?id=61 The Rockley Group, The Role of Content Standards in Content Management. Retrieved 12/11/08, from The Rockley Group, Website: http://www.rockley.com/articles/The%20Rockley%20Group%20-%20The%20Role%20of%20Content%20Standards%20in%20Content%20Management.pdf

References (cont.) Ethier, K. & Abel, S. (September 2004). Introduction to structured content management with XML. Retrieved 12/11/08, from CMS Watch, Website: http://www.cmswatch.com/Feature/112 Sen, D. & Dearth, R. (May 2005), Creating Context Sensitive Help Using Single Sourcing. Retrieved 12/11/08, from STC , Website: www.stc.org/edu/53rdConf/dataShow.asp?ID=56