XML DITA and Content Repurposing By France Baril

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 france. baril@ixiasoft. com www. ixiasoft. com