Creating Reusable Content

1
Creating Reusable Content
Using a Single Source for Information
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

2
3
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
4
Definition of Reusable Content

• Reusable content is used by businesses and
  organizations so the same information isnt
  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

5
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
6
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
7
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
• Users 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

8
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 users 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
9
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 Users Guides

• Uses
• Product name
• Price
• Description
• Feature List

Single source of information
To Create Brochures
Marketing Department

• Uses
• Product name
• Price
• Description
• Contact information

Online Content Writing Department
To Create Product Web Page
10
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
11
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
12
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
  users guide, online help, Web site, and brochure
• Example Billing information is used for a Web
  site only

12
13
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
  cant be reused for a quick reference guide that
  doesnt have an overview
• Cannot be arranged in a different sequence
• Example References to see below, and the
  following section

13
14
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 users guide has a section
  called Concepts whereas the online version does
  not

15
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

16
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

17
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

18
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

19
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.
• Sample text.
• Experience with computers
• Sample text.
• Sample text.

Figure 2 Keywords based on subject matter
assigned to various document elements
20
Methods for Reusing Content Structured Content
(cont.)
List Item 1
Figure 3 Outline representation of labeled
modules in a document
21
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 users
  guide and size 40 in blue Arial font for the
  brochure

22
Methods for Reusing Content Structured Content
(cont.)
Figure 4 Flowchart showing how structured
content and style sheets come together in a
software program to produce different information
products
23
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)

24
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

25
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

26
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)

27
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

28
Methods for Reusing Content Structured Content
Tools XML (cont.)

• ltchapter authorJohn Smithgt
• ltchaptertitlegtDesigning Step-by-Step
  Instructionslt/chaptertitlegt
• ltsynopsisgtWriting instructions requires
  knowledge of the products lt/synopsisgt
• ltlistgt
• ltitemgtWhat's the reading level of the
  user?lt/itemgt
• ltitemgt What is their experience with computers?
  lt/itemgt
• lt/listgt
• ltsectiongt
• ltsectiontitlegtReading level of the
  userslt/sectiontitlegt
• ltparagtsample textlt/paragt
• lt/sectiongt
• lt/chaptergt

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
29
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

30
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

31
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
32
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

33
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-di
  ta1/
• 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

34
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
35
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
36
Pros and Cons of Reusable Content Pros

• Reusable content
• 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

37
Pros and Cons of Reusable Content Cons

• Reusable content
• 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

38
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?p29
  753seqNum2
• Self, T. (March 2007). Semantic, Structured
  Authoring. Retrieved 12/11/08, from HyperWrite
  Consultancy and TrainingWebsite
  http//www.hyperwrite.com/Articles/showarticle.asp
  x?id61
• The Rockley Group, The Role of Content Standards
  in Content Management. Retrieved 12/11/08, from
  The Rockley Group, Website http//www.rockley.co
  m/articles/The20Rockley20Group20-20The20Role
  20of20Content20Standards20in20Content20Manage
  ment.pdf

39
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?ID56