XML, DITA and Content Repurposing

1. XML, DITA and Content Repurposing By France Baril

2. 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

3. 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 Agendas

4. TheoryContent 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 • …

5. TheoryContent repurposing • Purpose: The reason for doing something, similar to a goal, an objective. • Repurposing: Using with different objectives in mind.

6. TheoryXML useful characteristics • Separates content from presentation • Allows for process automation • Supports filters, conditional text • Allows multiple output types

7. TheoryXML process

8. TheoryDITA • 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

9. TheoryDITA useful characteristics • Is extensible • Is XML • Is modular

10. TheoryDITA and repurposing – basic level

11. PracticeThe 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

12. PracticeSet 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.

13. PracticeOverview of the content analysis

14. PracticeExample – Reference to training A B C

15. PracticeExample

16. PracticeIdentifying 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.

17. PracticeDefine 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.

18. PracticeFacing 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.

19. PracticeFacing the challenge

20. PracticeFacing 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.

21. PracticeFacing 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.

22. SummaryFrom 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!!!

23. SummaryFrom 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.

24. For more information Visit us at the IXIASOFT booth france.baril@ixiasoft.com www.ixiasoft.com