XML, DITA and
Content
Repurposing
By France Baril
Who is IXIASOFT?
•Launched in 1998
•TEXTML Server
 15 years of product development
 Application: Technical publication management,
publishing, knowledge management, editorial
archiving…
•DITA CMS solution
 First solution implemented in 2002
Agendas
Theory
•Define content
repurposing
•Learn about useful XML
characteristics
•Learn about useful DITA
characteristics
•DITA and repurposing –
basic level
Practice
•Set objectives
•Define what is
necessary for each
document type
•Adapt topic definitions,
if necessary
•Adapt XSL for each
output, if necessary
•Adapt style guide
•Create content
Theory
Content repurposing
•Some purposes of technical documents:
 Support current users
Reference guides, FAQs, tutorials, etc.
 Inform about a product (marketing)
Brochures, website pages, etc.
 Train different groups
Tutorials, formal training adapted to beginners, experts,
system administrators; or to pilots and maintenance
teams
 Sell a product
…
Theory
Content repurposing
•Purpose: The reason for doing something,
similar to a goal, an objective.
•Repurposing: Using with different
objectives in mind.
Theory
XML useful characteristics
•Separates content from presentation
•Allows for process automation
•Supports filters, conditional text
•Allows multiple output types
Theory
XML process
Theory
DITA
• DITA: an XML standard in evolution
• DITA: Darwin Information Type Architecture
proposes an information architecture based on
topics
• DITA is aimed at technical documentation
• DITA uses topics – small chunks of information that
can easily be reused across various contexts and
deliverables
• DITA topics can be “general” or “specialized”
• DITA specifies a number of topic types such a task,
concept and reference
Theory
DITA useful characteristics
•Is extensible
•Is XML
•Is modular
Theory
DITA and repurposing – basic level
Practice
The background
CEDROM-Sni is one of Canada’s largest news
content aggregator. They have online solutions
making it easy to manage information.
Challenges:
 Produce deliverables in three languages:
Solution:
 Create modular content
 Develop a custom DITA/CMS solution
 Publish context-sensitive information
Practice
Set objectives – An example!
•Reuse content in a reference guide to
support current users and for training of
new and current users.
•Reference guide is similar for everyone.
•Training is based on usage people make of
the tool. Need to adapt to each customer.
 Need to be able to create example based
tutorials that are more linear, less modular.
Practice
Overview of the content analysis
Practice
Example – Reference to training
A
B
C
Practice
Example
Practice
Identifying the challenges
•Maintaining multiple sets of tutorials.
•Maintaining dependencies between tutorial
topics.
•Basic XSL did not allow a topic to appear
twice in a PDF map.
•Deciding when to use an existing topic,
when to create a new one.
•Tutorials have a short lifespan. We don’t
want a mess.
Practice
Define how to meet the objectives
•Reorder topics to match the different
contexts.
•Add tutorial information.
•Filter tutorial information based on:
 Document type.
 Section id provided in the map (a task might
appear more then once in a tutorial).
 Tag information that may not appear in tutorials
with tutorial=no.
Practice
Facing the challenges
• Maintaining multiple sets of tutorials.
and
• Maintaining dependencies between tutorial topics, following
linearity.
Create one file of tutorial information for each tutorial.
Reference the tutorial information from topics.
Avoids the mess from too many conditions we already had:
 11 audiences
 4 products (3 basic + new one)
 A few partners (custom sites – extra along the way)
Use conditions based on tutorial id.
Provide a tutorial id in the map and topics.
Program the CMS to identify topics that have changed ‘since
last published’ and flag them for review.
Practice
Facing the challenge
Practice
Facing the challenges
•Deciding when to use an existing topic,
when to create a new one.
When the steps are in the exact same order
(1 to 1 match).
Otherwise, simple include a dependency in
metadata for CMS to flag tutorial info that
might need changes.
Practice
Facing the challenges
•Tutorials have a short lifespan. We don’t
want a mess.
Create a procedure that finds tutorial ids in
topics and deletes either the id or the
element if referenced by only one tutorial id.
Summary
From your needs to your DITA usage
• Using DITA basic types doesn’t mean not to spend
time on the content model.
• Even without specific specializations, you must plan
how you are going to use the topics to meet
specific needs.
• XSLs from the toolkit are great to get started, but
don’t let them dictate what you can or cannot do.
Extend processing capabilities, if need be.
• Think in terms of mess… would this be to hard to
maintain?
• FIX YOUR OBJECTIVES FIRST!!!
Summary
From your needs to your DITA usage
•There is an overhead to working like this.
 Time to develop stylesheets
 Time to define tutorial info
•Worth it?
 1 writer / 1 trainer / 1 contractual translator
 Training customized for each client!!!
 Write topics once, change the tutorial info
 Most tutorials are not reused.
• Not too much of a domino effect on changes.
• Notified if necessary.
For more information
Visit us at the IXIASOFT booth
[email protected]
www.ixiasoft.com