Discuss the layers of topic-based authoring, best practices for writing at the topic level, single sourcing publishing opportunities and strategic planning to meet challenges along the way.

1. Topic-Based Authoring
and Reuse
Mollye Barrett

2. Terms
•
•
•
Single sourcing is a method of developing reusable content
that can be assembled to create publications; different
combinations of topic modules result in separate publications
Modular writing is a technique that makes single-sourcing
possible. Modular, or topic-based, writing is a type of
document design and architecture where content is
structured into independent small modules (topics) which can
be assembled into one or many larger texts, such as a books,
Web sites and Help systems
Content life cycle is a process that includes every content
state and the tasks associated with that state from
discovery to delivery

3. Content Life Cycle

4. Why Topic-Based Authoring?
Authoring in structured topics decreases development costs and
time to market, Topics:
• Contain only the information needed to understand one
concept, perform one procedure, or find one set of reference
information
• Increase consistency in the presentation of similar information
• May be reviewed by subject-matter experts when ready
• Assembled into multiple deliverables can be automated,
reducing production time and costs
• May be reused in multiple deliverables if consistently
structured
• May be updated immediately: no need to wait for the next
release of an entire library of documents

5. Who Does Topic-Based Authoring?
•
•
Technical communicators deliver information that transmits a
useful, accurate message that is easy to understand, and helps
non-expert's get through the material
Communicate useable information, not pleasure reading
• Topic-based content does not always read well
• Unlike a novel, users search for and read only the topic
needed

6. About Topic-Based Authoring 1
•
•
A topic is a unit of information with a title and content,
short enough to be specific to a single subject.
The smallest amount of content that allows for the
successful completion of a task, or that provides basic
knowledge of a concept.
• Online help topics: goal-based not pleasure reading

7. Topics, Reuse and Publishing
7

8. About Topic-Based Authoring 2
•
•
•
•
•
Remove context from the content for reuse
Assemble topic from a repository into different publications for
delivery in different reading formats.
• Critical for managing large documentation suites with
substantial common content
When executed well, topic based authoring and publishing
does not decrease quality; requires substantial discipline
Writers don’t “own” content, content is a business asset reused
by everyone
Writers have less control over look and feel when published

9. About Topic-Based Authoring 3
•
•
•
•
•
•
Topics are standard units of information based on type
Topics require only navigational reference for context and may
be read in any order
Topics are a single unit of work for an author
The number of topics required to create a deliverable increases
substantially over linear document-centric narratives
Must be able to track topics, name and version
Store content in an indexed repository; avoid folders use
standardized naming convention

10. What Prevents Content Reuse?
•
•
•
Format
• Incompatibility
Poor structure
• Structure provides a framework, or set of fixed “buckets”
into which writers can drop content. Deviation produces
errors…structure enforces compliance. Hard to do
outside structure.
Inconsistency
• Content varies in terms, grammar, tone, style, diction,
voice, tense
10

11. Making Topic Based Authoring
and Reuse Happen
Creating useful topics for effective reuse must be planned!
• Adopt a model to define structure and indicate reuse
• Create writing guidelines that define how to write to
structure
• Create modular content – easily accessed, assembled,
updated, consistent
• Follow standards – all writers, all the time, no exceptions
• Make content usable – no filler
• Design content and structure to accommodate differences
11

12. Writing Guidelines
Define how to write for user:
• Reading level
• Expertise
• Where read
• Publication
Producing one publication for the same reader is easy.
Managing multiple publications from the same source is a
challenge and a single style guide is essential.
12

13. How Structure Helps
•
•
•
Does not help with voice, word choice, tone, etc., but can help
with:
• Required parts of topic (e.g. prereq, example, result)
• Acronym/term definition (e.g. conref, keys, abbreviatedform)
Using structure relieves writers of need to remember
mechanics like:
• End each task with a result
• Add a caption to each figure
Writers are free to concentrate on writing
13

14. Topic-Based Authoring Tools
Author
•
•
•
XML
XMetal
oXygen
Author and publish
•
•
•
•
FrameMaker
MadCap Flare
RoboHelp
Word
Content Management System
•
•
•
Author
Publish
Manage
Manage
•
•
•
•
Folders
Excel
SQL, Access, Oracle,
RCS, SCCM, Subversion

15. References
•
•
•
Ament, Kurt. Single Sourcing: Building Modular
Documentation. Norwich, NY: William Andrew Pub., 2003
Bazerman, Charles. "The Production of Technology and the
Production of Human Meaning." Journal of Business and
Technical Communication 12.3 (1998)
Hargis, Gretchen. Developing Quality Technical Information:
A Handbook for Writers and Editors. Upper Saddle River, NJ:
Prentice Hall Professional Technical Reference, 2004

16. Thank You
Mollye Barrett
ClearPath, LLC
mollye@clearpath.cc
16