1. We’ll start at 3 minutes after the hour
Make sure your sound is working
10 mistakes when
moving to topic-based
authoring
Sharon Burton Twitter: #10MistakesTBA
E-mail: Sharon@sharonburton.com
Tweet: Sharonburton

2. 10 mistakes when
moving to topic-based
authoring
Sharon Burton Twitter: #10MistakesTBA
E-mail: Sharon@sharonburton.com
Tweet: Sharonburton

3. Twitter: #10MistakesTBA
Who am I?
▪ I’m Sharon Burton
▪ Been in the Tech Comm industry for
nearly 20 years
▪ Content Consultant
▪ STC Associate Fellow
▪ Teach:
▪ Technical Communication to Engineering
students at the University of California, Riverside
▪ Tech Comm certificate program at UCR Extension
▪ Society for Technical Communication Certificate Courses
▪ I knit, design patterns, work out, write, garden, have a
large dog, and am all around just fun

4. Twitter: #10MistakesTBA
Supporting role today…
▪ Bonni Graham is supporting us
▪ If you have a question, Bonni will help you in the
questions window
▪ We’re doing a live Q and A at the end
▪ We’re recording this webinar
▪ Slides are available on SlideShare
▪ Let’s also say “Thank you” to ProSpring Technical
Staffing for sponsoring these webinars
▪ http://prospringstaffing.com/
▪ www.lavacon.org

5. What is topic-based
authoring?
Quick definition

6. Twitter: #10MistakesTBA
Definition
▪ Topic-based authoring is a modular content creation approach
(popular in the technical publications and documentation arenas) that
supports XML content reuse, content management, and makes the
dynamic assembly of personalized information possible.
▪ A topic is a discrete piece of content that is about a specific subject, has
an identifiable purpose, and can stand alone (does not need to be
presented in context for the end-user to make sense of the content).
▪ Topics are also reusable. They can, when constructed properly
(without reliance on other content for its meaning), be reused in
any context anywhere needed.
▪ The Darwin Information Typing Architecture (DITA) is a standard
designed to help authors create topic-based content. The standard is
managed by the Organization for the Advancement of Structured
Information Standards (OASIS) DITA Technical Committee.
From Wikipedia

7. What is Topic-based Authoring?
▪ Focuses effort on the information your user needs to
use the product
▪ Develop a body of information that’s helpful to the user
▪ Maximize content reuse
▪ Roughly similar to structuring an online help system
▪ People who’ve developed a lot of help “get” these concepts
faster
▪ If you are moving to DITA, it’s part of the trip
▪ But you don’t have to move to DITA to make use of this
information development method
▪ This can be a destination as well as a rest stop

8. Twitter: #10MistakesTBA
What is Topic-based Authoring?
▪ Topics are small, perhaps ½ to 4 printed pages
▪ Perhaps smaller
▪ Only include the information needed to
▪ Perform one procedure
▪ Understand one concept
▪ Topics can be (re)combined
▪ New products, deliverables, or other ways
▪ Topics are easier to update
▪ Easier and cheaper to get approval for updating topics from
management
▪ Depending on deliverables, push updated topics to your
users

9. Twitter: #10MistakesTBA
What is Topic-based Authoring?
Library
Adding About
Programming
Users
Objects and
Relating Inheritance
Objects Importing
Placing Setting
Objects
Reports
Permissions
Containing Editing
Objects Reports
Deleting Printing Setting
Reports Schedules
Users About
About
Objects Reports
Using
Container
About Objects
Schedules
About Users
Customizing
Objects
Saving
Creating reports
Reports
Exporting
Objects
About
Containment

10. Twitter: #10MistakesTBA
What is Topic-based Authoring?
Library
Admin Guide Programmers Guide Getting Started
• About Users • About • About Users
• Adding Users Programming • About Reports
• Deleting Users • About Objects • About
• Setting • Placing Objects Programming
Permissions • About • About Objects
• About Reports Containment • About
• Creating Reports • Objects and Containment
• Editing Reports Inheritance • Exporting Objects
• Saving Reports • Using Container • About Schedules
Objects
• Printing Reports
• Customizing
• Importing Reports
Objects
• Relating Objects

11. What are the mistakes?
How to mess this up

12. 1: Not getting buy-in
▪ This is not going to be an
instant and dramatic
improvement
▪ Except localization
Management and ▪ Costs may drop immediately
other teams need
to understand ▪ Schedules may be impacted
why this is better
and you have to ▪ Less content can be scary
show that.
Maybe a business
case?

13. 2: Using the same tools
▪ The tools that got you into this
mess are probably not the
tools to get you out
Asking Techwr-l ▪ Evaluate what your needs are
what they use now and in the future
and buying that
not the answer. ▪ Work with the vendors closely
What are your to make sure what you need is
problems and what they can do
what are your
solutions?

14. 3: Using the same processes
▪ Developing topic-based
content is different
▪ Topics “stand alone” on
The processes for content and/or formatting
developing, editi
ng, and ▪ Topics are reviewed as they
publishing a 200 are ready
page manual
won’t work. ▪ Review process must change
▪ Maybe use a special review
product

15. 4: Not training people
▪ New tools + new process =
training
▪ Training provides more than
Not training sets how to use the product
up projects and ▪ Includes best practices for our
people for failure. workflow
You can’t expect ▪ Identifies the changes for our
people to workflow
magically know.
▪ Instantiates how we do what we
do

16. 5: Not planning the move
▪ Your legacy content is not going to
fit neatly
▪ It’s at least not well written/structured/
organized
▪ One manual/help may not give you
You can’t jump on the real picture
your horse and ▪ Especially if you had a lot of
contractors, the legacy content has
ride off in all been around a long time, and so on
directions.
Analyze what you ▪ This can be very hard on the staff
▪ People want their content to be the
have before you exception
decide what you ▪ It’s special content, not like other
have content and needs special attention

17. 6: Not using writing guidelines
▪ Before we can start thinking
about moving to topic-based
authoring
▪ And gaining the benefits thereof
We must have ▪ Content reuse demands
good writing consistent writing standards
standards in
place. ▪ The content can appear in many
places
▪ In more than one deliverable
▪ Everyone cannot write in
“their style”

18. 7: Slicing content according to
headings
▪ That’s step #1 of x and x is
bigger than 2
▪ Now you need to think about
Because most ▪ Content reuse
tools allow you to ▪ Smaller topics
import and slice
your legacy ▪ Embedded topics (snippets)
content based on ▪ Localization
headings, it can
feel like you’re ▪ Outputs
done after you ▪ Devices
import.
▪ More

19. 8: Not reusing content
▪ You can’t reuse what you can’t
find
▪ Opportunistic reuse
▪ People remember this content
from before
Writing content is ▪ Maybe they can find it
expensive. ▪ Big time sink
Re-creating
existing content ▪ Systematic reuse
is very expensive. ▪ The system knows this content has
Localizing similar been written previously
but different is ▪ Prompts the writer for reuse
really expensive. ▪ Tracks reuse and reports it

20. 9: Not considering audience
▪ Your users are not stupid
▪ They know how to use Windows
▪ They know their jobs
Identify your ▪ Most users are intermediate
audience and users
their schemas.
Identify their
domains of
knowledge.
69% of your users
are intermediate
level.

21. 10: Thinking this is trivial
▪ It won’t take any time to figure
this out
▪ We can do this as we need to
Your legacy
content is not
▪ It’s easy
going to fit neatly
in content ▪ We’ll hire an intern to do it
categories.
▪ We can meet deadlines while
we completely restructure all
our content

22. 11: (Bonus) We don’t need to worry
about Localization
▪ If you are not localizing now,
you will be in the future
▪ If you are localizing now, you
Always act like know how complicated it can
you’re going to be
localize and ▪ Someone will decide to add
nothing bad more languages
will happen to
you.
▪ Because that’s not a problem,
right?

23. More information
Resources for more information

24. Good reading resources
▪ Single Sourcing: Building Modular Documentation
by Kurt Ament
▪ ISBN-10: 0815514913 or ISBN-13: 978-0815514916
▪ Content Strategy 101: Transform Technical Content into a
Business Asset
by Sarah S. O'Keefe and Alan S. Pringle
ISBN-10: 0982811845 or ISBN-13: 978-0982811849
▪ Content Strategy: Connecting the dots between
business, brand, and benefits
by Rahel Anne Bailie and Noz Urbina
ISBN-10: 1937434168 or ISBN-13: 978-1937434168

25. These are good, too
▪ Wait a Minute, I Have to Take Off My Bra, 2011.
ISBN-10: 0981333516.
▪ Anthology of creative non-fiction and poetry
▪ My first creative non-fiction book publication!
▪ 8 Steps to Amazing Webinars, 2012
ISBN-10: 1937434044
▪ Available from Amazon and Barnes and Noble

26. Questions?
Contact me:
E-mail: Sharon@sharonburton.com
Twitter: Sharonburton