Improve your Chances for Documentation Success with DITA and a CCMS LavaCon Las Vegas 2016

Keith Schengili-Roberts
DITA Evangelist, IXIASOFT
Improve Your
Chances for
Documentation
Success with DITA
and a CCMS
+

Agenda
• Introduction
• Overview of Key Features of DITA
• Four Chief Reasons for Wanting to Move to
DITA + CCMS
• Four Things You Can Do with DITA and a
CCMS
• Q/A

Who’s This Guy?
Keith Schengili-Roberts
IXIASOFT DITA Evangelist
and Market Researcher
What I do:
• DITA evangelist
• Liaison with OASIS; on DITA
Adoption and Technical Committees
• Industry researcher
• Lecturer on Information Architecture,
University of Toronto
• 10+ Years of DITA XML experience

Also Known As “DITAWriter”
• Industry blog started +5 years ago
• Just over 220,000 hits
• Regularly updated info on:
 DITA Conferences
 DITA Books
 Companies Using DITA
 DITA CMSes
 DITA Editors
 Other DITA Tools
 DITA Consulting Firms
• News/views on DITA use
• Features interviews with those
making a difference in the world
of DITA

Any STC Members Here?
• Much of this
presentation is based
on my article published
in last month’s STC
magazine Intercom
• I plan to expand upon
its points and go into
more details than
space allowed in the
original article

What is this DITA Stuff?
• It’s an open XML standard for
creating structured content built
primarily around the idea of content
reuse
• Has been around for just over 10
years, has gained significant
traction in technical authoring
community
• DITA is used by ~5% of all technical
writing groups in North America
(and still growing!)

Reuse is Built-in to DITA
• DITA was built around
the idea of content
reuse
 This has helped make
DITA the fastest
growing XML-based
technical
communications
standard

DITA Content Reuse = Consistent Messaging
• Benefit of consistent content and messaging
• Consistent content means consistent user
experience
 Along with being seamless, available and context-
specific

Reduced Localization Costs with DITA
• Content reuse in English = localization savings
• If many target languages, ROI argument for moving
to DITA (+ CCMS) is easier
More on this later…

Separation of Form from Content
• In a study I did prior to moving
to DITA at AMD, found that
fully half of the time spent
using DTP software was on
formatting content
• Suggests considerable time
savings, making content
creators more nimble and able
to concentrate on making
additional content

DITA Was Built
with Multi-channel Publishing in Mind
• This was a key design feature when DITA was still being
devised at IBM; intent was to tame a multitude of output
processes then in place with a single
• DITA-OT by default supports 11 output types, including PDF,
RTF, HTML5/XHTML
• Other output types possible

FOUR CHIEF REASONS FOR
WANTING TO MOVE TO
DITA + CCMS
A look at the tools in DITA for creating reusable content

Pain Points
that DITA + CCMS Can Solve
• Need to be more efficient/do more with less
• Have outgrown current toolset
• Escalating localization costs
• Requirement to verify content before it goes out the
door
• In addition you also
get to be one of the
“cool kids” ;)

Need to Be More Efficient / Do More with Less
• For many documentation teams it
is not possible to get more
headcount
• Need to reduce localization costs
• DITA + CCMS has a proven track
record for improving overall
costs + efficiency
 Does not come for free however;
there is a need to justify costs of
moving to DITA + CCMS
(stay tuned!)

Have Outgrown Current Toolset
• Traditional Desktop Publishing tools cannot cope
with growing need to produce content
• Hard for writers to find existing material for reuse
in file folders or existing repositories
• Pressing need to automate existing processes
• Seeking a more mature process

Escalating Localization Costs
• Ongoing need to produce localized
content, but costs (especially with
desktop publishing-based
processes) have become prohibitive
• Additional costs are incurred for:
 Formatting content
 Fixing code-page errors (a glyph is
transformed into a different character)
 Sending more content than necessary
for localization

Requirement to Verify Content
Before it Goes Out the Door
• In regulated environments such as in the medical
device sector, content must first be vetted by
medical professionals
• Similar requirements in other sectors, such as legal
publishing, heavy manufacturing, etc.

Becoming One of the “Cool Kids”
• I actually wasn’t kidding about this one…
• DITA has been adopted by documentations teams
at over 650 companies worldwide

This in Turn Adds
to the Spread of DITA

On a More Personal Level…
• Those who learn DITA often go on to work at other firms
where they are sometimes hired specifically for this skill
48,000.00
50,000.00
52,000.00
54,000.00
56,000.00
58,000.00
60,000.00
62,000.00
64,000.00
66,000.00
Q1 2016 Q2 2016 Q3 2016
Avg. Starting Wage for Technical Writers on Indeed.com for
2016
Tech Writer Tech Writer + DITA Linear (Tech Writer) Linear (Tech Writer + DITA)

Some Other Possible Reasons
for DITA + CCMS
• Need to produce additional deliverable types
(for additional products, additional platforms, etc.)
• Need to produce filtered/custom deliverables
• Need to interchange with other groups using DITA
• Need to move from a custom XML tagset to DITA standard
for greater scalability/maintainability outside support
 In so doing, also get to join a growing community of
people working with DITA

FOUR THINGS YOU CAN DO
WITH DITA AND A CCMS
What a CCMS has to offer

#1: Versioning of Content
• A feature common to most
content management systems,
though not to most file systems
• Originally created for software
development, versioning
allows users to “check out”
content for authoring and
“check in” any changes

CCMS and the Versioning of Content
• A typical CCMS will have versioning capabilities that
ensures that only a single technical writer can work on a
given topic at any one time, and will also register who made
which edit and allow for a quick comparison between
versions
• Any documentation “bugs” that are discovered in a later
version of a topic can be reverted to an earlier version
without the problem

#2: Workflow
• Once a writer has
completed writing a
topic, can then be
routed automatically
• Useful for when you
need to have content
edited/verified before it
goes out the door
• Introduces ways to
improve content quality
Information Architect
Data Collection
Engineer Editor
Technical Writer

Typical Workflow Examples
• An example: a Subject
Matter Expert (SME) may be
assigned within the system
to write content which is then
“polished” by a technical
writer, and then sent to
another SME for approval
• Or: technical writer creates
content, is routed to another
writer/editor who verifies
quality
Engineer
(SME)
Technical
Writer
Engineer
Who Approves
Content
Accuracy

#3: Measurement
• Having modular content
opens up the possibility
of measuring content
production more
accurately
• Not every topic will be
the same size, but
there will be an
average value
+

DITA and
Return on Investment (ROI)
• This has been a primary focus
of much work on DITA metrics
• Topic-based nature of DITA
lends itself to cost-based
measures
• The book DITA Metrics 101
(2013) looks at this aspect
almost exclusively, focusing
on justifying the cost of
investing in DITA + CMS

DITA Metrics
for Production Purposes
• But not everything is about ROI:
 What if you have a mature DITA environment and have
already established your ROI?
 Or, are simply looking for ways to use DITA + metrics to
measure things that are not cost-related?
• DITA metrics can be used
to guide managers,
information architects and
writers on how to improve
their content

DITA Production Metrics
without a CMS
• DITA metrics outside of a
CMS are limited to
information contained within
the DITA files + file system
 Can search for text strings
within the XML, and also use
date/time info from filename…
and that’s about it

DITA Production Metrics
with a CMS
• DITA metrics within a CMS can capture additional information,
which depending on the CMS may include things like:
 Author information
 Workflow status
 How many times a topic has been modified/versioned
 Topic/map dependencies
• In general, can also expect CMSes to have “canned” search
routines that make the task of mining information from your
DITA content easier

• At Scrum meetings doc
manager can report on
topics assigned to their
group and report on how
“done” they are
• This is typically only feasible
within a CMS containing
workflow metadata
“Our project managers could track progress of
documentation deliverables within our DITA-
based CMS on a daily basis.”
- Jason Owen
Agile and DITA Metrics

Content Types
within All Documents Over a Year
• This chart looks at the DITA topic
breakdown for all documentation
produced by IXIASOFT in 2015
• Documentation consists of
User/Admin Guides for our DITA
CMS and TEXTML software
• Good ratio of concept to task topics
• When I showed this to our Lead Tech
Doc person, she immediately wanted
to investigate the 3% of generic topic
types
 Nice practical example of how DITA
metrics can improve quality!
Count: 1307

Can Easily Find Content
that is Revised a Lot
• A topic that is often revised might be a sign that it needs to be
investigated; perhaps too much tweaking is happening, or there is SME
disagreement, or it should be multiple topics instead of just one
0 1 2 3 4 5 6 7 8 9 10
System performance
Logging on to
About
Image Warehouse
Frequently Asked Questions
Query filters
Cluster capacity reports
System diagnostics
Customize Views
About this guide
Generating data views
Number of Revisions per Topic in the Thunderbird User Guide
!

Example of How CCMS Data Can
Be Mixed with Outside Data: Cost-per-Topic
• Idea came from a CIDM Best Practices article by Mike
Eleder (“The Illusive, Writing Productivity Metric:
Making Unit Cost a Competitive Advantage”)
• Basically:
cost per topic = monthly tech writer team cost
topics produced monthly
• This is a unit cost measure, and it produces the
monthly average cost for producing topics
 Can estimate the cost of future work based on result

Example Chart
Showing COST-Per-Topic
• The trend line records the average cost-per-topic over the time measured
• This shows an overall downward trend: ideally this is what you would expect
over time
• Same cost measures can be applied to published documents, localized content
and more
$

An Example of This
Using Localization Spend
• ROI for move to DITA + CMS justified in terms of unspent localization
budget due to efficiencies

#4: Localization
• Reduced localization costs
come from DITA reuse
 Content reuse in English =
content reuse in other languages
• A CCMS provides additional
benefits:
 Improved packaging options
 QA as part of localization
workflow
 Automation
Illustration of how DITA localization
without a CCMS typically works

Improved Packaging Options
• In addition to sending content
in DITA, also possible for
CCMS to transform content
into XLIFF
• Can also automate inclusion
of PDF for context
• Also possible to send
individual topics/changes for
translation

QA as Part of Localization Workflow
• A good DITA CCMS will include localization QA as
part of the workflow for content
• Enables checking and verification of content prior to
publication
• Can easily route “bad” localized content back to
localization service provider

Automation
• A capable DITA CCMS will
enable a firm to automate
localization processes
• Some of IXIASOFT’s
customers send individual
topics out for localization while
rest of document being
worked on
 New and changed content can
be merged, enabling much faster
turnaround times
Writing: Complete
Localization: Complete

Other Things
a DITA CCMS Can Do for You
• Provides a mechanism for SMEs to contribute
directly to content
• Looking to move away from PDF? Can use
DITA + CCMS with dynamic publication engines to
create HTML5-based publications
• Metadata embedded in DITA maps and topics can
aid with search engine optimization

Upfront Costs vs. Opportunity Costs
• Yes, there are often significant costs
associated with purchasing a DITA
CCMS:
 Conversion costs of legacy content
 Change management
 Cost of CCMS software
 May involve separate purchase
of repository software for content
• But can your organization support
ongoing costs of current toolchain?
 This is an opportunity for change and
improvement…

DITA + CCMS = The Road Ahead
• DITA + CCMS should be thought
of as an opportunity to improve
the quality of your content and
your documentation processes
• Think of where you need to take
your documentation team and
what your users will expect of
you five years from now

QA
• Blog: www.ixiasoft.com/en/news-and-events/blog
• Twitter: @IXIASOFT (and @KeithIXIASOFT)
• IXIASOFT DITA CMS Users LinkedIn group:
www.linkedin.com/groups?gid=3820030
• OASIS DITA Adoption Committee articles
• Member of OASIS DITA Technical Committee

Improve your Chances for Documentation Success with DITA and a CCMS LavaCon Las Vegas 2016

More Related Content

What's hot (20)

Similar to Improve your Chances for Documentation Success with DITA and a CCMS LavaCon Las Vegas 2016 (20)

More from IXIASOFT (15)

Recently uploaded (20)

Improve your Chances for Documentation Success with DITA and a CCMS LavaCon Las Vegas 2016

Editor's Notes