XML, DITA and XML, DITA and Content Content

Repurposing Repurposing

By France Baril

Who is IXIASOFT?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

AgendasAgendas

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

TheoryTheoryContent repurposingContent 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 …

TheoryTheoryContent repurposingContent repurposing

•Purpose: The reason for doing something, similar to a goal, an objective.

•Repurposing: Using with different objectives in mind.

TheoryTheoryXML useful characteristicsXML useful characteristics

•Separates content from presentation•Allows for process automation•Supports filters, conditional text•Allows multiple output types

TheoryTheoryXML processXML process

TheoryTheoryDITADITA

•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

TheoryTheoryDITA useful characteristicsDITA useful characteristics

•Is extensible•Is XML•Is modular

TheoryTheoryDITA and repurposing – basic levelDITA and repurposing – basic level

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

PracticePracticeThe backgroundThe background

PracticePracticeSet Set objectives – An example!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.

PracticePracticeOverview of the content analysisOverview of the content analysis

PracticePracticeExample – Reference to trainingExample – Reference to training

A

BC

PracticePracticeExampleExample

PracticePracticeIdentifying the challengesIdentifying 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.

PracticePracticeDefine how to meet the objectivesDefine 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.

PracticePracticeFacing the challengesFacing 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.

PracticePracticeFacing the challengeFacing the challenge

PracticePracticeFacing the challengesFacing 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.

PracticePracticeFacing the challengesFacing 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.

SummarySummaryFrom your needs to your DITA usageFrom 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!!!

SummarySummaryFrom your needs to your DITA usageFrom 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 informationFor more information

Visit us at the IXIASOFT booth

france.baril@ixiasoft.com

www.ixiasoft.com