Creating Reusable
Content
Using a Single Source for Information
© M. Reber
6/27/2016
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
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
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
4
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
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
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
7
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
Examples of Reusable Content (cont.)
Figure 1: Chart showing how several departments use
content for different information products in different formats
Single source
of
information
Technical
Writing
Department
Uses:
• Product name
• Description
• Assembly instructions
• Activation information
Marketing
Department
Uses:
• Product name
• Price
• Description
• Feature List
To Create:
Brochures
Online
Content
Writing
Department
Uses:
• Product name
• Price
• Description
• Contact information
To Create:
Product Web Page
To Create:
User’s Guides
9
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
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
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
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
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
14
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
15
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
16
Methods for Reusing Content:
Conversion Tools (cont.)

Popular conversion tools:
 Quadralay WebWorks ePublisher: converts printbased 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
17
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
18
Methods for Reusing Content:
Structured Content (cont.)
Designing Step-by-Step Instructions
chapter title
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:
list item 1
What's the reading level of the user?
synopsis
 What is their experience with computers?
list item 2
section title A
Reading level of the users
Sample text.
Paragraph 1A
Sample text.
Paragraph 2A
section title B
Experience with computers
Sample text.
Paragraph 1B
Sample text.
Paragraph 2B
Figure 2: Keywords based on subject matter assigned to
various document elements
19
Methods for Reusing Content:
Structured Content (cont.)
Chapter Title
Synopsis
Chapter
List
Section
Section
Figure 3: Outline representation of
labeled modules in a document
List Item 1
List Item 2
Section Title
A
Paragraph
1A
Paragraph
2A
Section Title
B
Paragraph
1B
Paragraph
2B
20
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
21
Methods for Reusing Content:
Structured Content (cont.)
Structured
content
labeled with
keywords
Style sheets
for each type
of output
format
User’s
Guide
Software that
applies
formatting rules
in style sheet to
content
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
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)
23
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”
24
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
25
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)
26
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
27
Methods for Reusing Content
Structured Content Tools: XML (cont.)
attribute
<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>
start tag
end tag
<item> What is their experience with computers? </item>
</list>
element
<section>
<sectiontitle>Reading level of the users</sectiontitle>
<para>sample text</para>
</section>
</chapter>
Figure 4: A document written in XML. The callouts identify an
attribute, start and end tags, and an element
28
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
29
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
30
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
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
32
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
33
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
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
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
36
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
37
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%20Managem
ent.pdf
38
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
39