Converting your legacy documents to xml dita


Published on

This article is published by Sudhir Subudhi, a Senior Technical Writer and DITA Consultant. The article discusses about the reasons and strategic requirements to undertake a DITA conversion project, involved technical aspects in the project, typical roles played by people in the project, the conversion process, the need of dita specialization and customization, and the need of an expert dita consultant to help effective progress and delivery of the project.

Published in: Business, Technology
1 Like
  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Converting your legacy documents to xml dita

  1. 1. Converting your legacy documents to XML-DITA by Sudhir Subudhi 1 Converting your legacy documents to XML-DITA Prepared by: Sudhir Subudhi, Senior Technical Writer and DITA Consultant LinkedIn Profile: Email: Skype Name: sudhir.subudhi Introduction Many companies, small or big, working in non-DITA standard documents, are experiencing problems in terms of managing the documentation set, meeting the documentation delivery requirements at a minimal cost, and integrating the documentation set to their core knowledgebase and organizational content. In future: Many delivery formats will rely on the same source content Vendors would require to finely design their content for economical delivery Companies will be required to integrate the documentation set to the core knowledgebase of the company, product UI, and organizational content Vendors would resort to higher documentation technology to beat the competition DITA has tremendous scope in this upcoming business environment! It will work as an enabler for the companies to achieve these business requirements. That’s why there is a trend to convert the legacy unstructured documents to DITA, and keep using DITA onwards. There are many points to consider while executing the DITA conversion project in a company, including the following: Understand that the requirement is not only to convert the unstructured content to DITA topics, but also to make use of converted content to achieve the company’s new expectations. The new design of the content should have scope to seamlessly merge with the knowledge base of the company, product UI, and organizational content. The information architecture of the new documentation set must be designed. Specialization and customization should be done. The Task Analysis and Audience Analysis of the product must be done. Make content as granular as possible, so that the same could fit at any level of information required across documentation, product and organization. There are tools to make automated conversion possible for large documentation sets. However these are not full-proof. Given the fact that the target documentation set will be of a complete new architecture, and looking at the goals the company is trying to achieve, it is recommended to have a manual conversion process with the guidance of an Information Architect. The auto-conversion process can be implemented together with manual efforts as well. The following could be the possible scenarios for a company’s current state and plan of action: Company is having legacy documents in non-DITA format and wants to convert all the documents to DITA at one go without hampering their release cycle. The new format may not
  2. 2. Converting your legacy documents to XML-DITA by Sudhir Subudhi 2 offer anything new, but must be a refined and usable set of the existing content. The company plans to evolve its DITA documentation there on, release by release. Company is having legacy documents in non-DITA format and wants to convert the documents to DITA phase by phase without hampering their release cycle. First it wants to release documents for a product in DITA as a pilot. Then it wants to convert documents for other products to DITA release by release according to their available bandwidth. Company wants the new DITA format to meet all their expectations. The new format must overcome all the laggings of the legacy documentation. The new format must convert the existing content and must add the new required content as well. The company wants to achieve all these in the next release. The conversion process can be cost and resource intensive as per the level of conversion a company wants to implement. A conversion project must be undertaken to achieve the desired goals successfully. It’s recommended to execute the conversion project iteratively to include a learning and mistake correction mechanism. Typical roles played by people in a conversion project Senior Management Evaluates the conversion proposal, decides on the conversion, signals go ahead Information Architect Proposes new design, designs information architecture, trains technical writing team, assists in the conversion process Cross-functional teams Analyze and study new design, cooperates with the documentation tam, help in technical and usability review of new documentation set Documentation manager Plans conversion project, monitors progress and completion using milestones Technical Writing team Follows the design and plan, converts legacy documents to DITA topics, writes new topics, reviews converted and newly written topics, collaborates with other cross functional teams, reports progress Customers Provide feedback on the new design and approach Conversion Process as a whole 1. Study the product and its existing documentation set. Also study the inside delivery process and operations of the company and use of the product at end-users side.
  3. 3. Converting your legacy documents to XML-DITA by Sudhir Subudhi 3 2. Perform audience analysis and task analysis of the product. 3. Design the architecture of the target information deliveries in DITA. Perform DITA specialization and customization as applicable. It’s welcome if you can prepare a prototype of the new design to present a demo to the senior management and customers. Also you can perform a usability review of the new architecture. 4. Convert the existing documents content to DITA topics. 5. Write new content whenever required. 6. Trash or don’t convert unnecessary topics or content. Ensure to archive the old content somewhere for future reference, in case it’s required. 7. Publish the documentation for reviews and testing. Audience Analysis and Task Analysis While converting to a new design it’s important to perform the audience analysis and task analysis of the product. Also study the inside delivery process and operations of the company and use of the product at end-users side. This ensures that the new documentation set is task oriented and meets all the help requirements of the users. This analysis can be found in the existing Software Requirement Specification, Functional Specification, or Software Design Document of the product. If you don’t have such documents readily available, then you must perform this analysis afresh. Maintaining a Fact-sheet It’s important to maintain a fact-sheet for the conversion project. The fact-sheet would contain facts or information regarding the product, organization, industry, clients, end-users, content delivery items, delivery formats, specialization, filtering criteria, etc. The fact-sheet needs to be evolved throughout the conversion project and must be in sync with the Information Architecture of total DITA content. Creating Target Information Architecture or Model The target information architecture should have the following: Information Delivery names and their delivery formats Ditamaps (or specialized ditamaps) for every information delivery Topic store containing Concept/Task/Reference/Specialized topics reusable across information deliveries, product UIs, and organizational content. Customized XSL files to produce desired look and feel in the output formats Converting a particular document to DITA 1. Study the document and derive the DITA Topics/elements by using the following table: Note: The table explains a sample task to demonstrate how to club a task and other supported topics together. It also describes how to find reusable structured information types and elements.
  4. 4. Converting your legacy documents to XML-DITA by Sudhir Subudhi 4 Tasks explained in the document Supporting Concepts Supporting Reference topics and other supported topics to execute the task Derived/Reusable/st ructured Information Types or Elements Starting ABC software About ABC software Troubleshooting1: Invalid license Troubleshooting2: System not responding FAQ1: What is ABC? FAQ2: Who are the users of ABC? Glossary term1: ABC Logos and Labels for ABC software Troubleshooting FAQ Glossary term Task 2 Task 3 … Task <n> 2. Create blank DITA topics for the topics listed under the first three columns of the table. Write these topics by copying, pasting, and modifying the applicable content from the existing document. Store the topics in your topic store. 3. Follow the same for other tasks explained in the document. 4. Scan the document, from beginning to end, to find if there are any other content that must be converted and stored in topic store for later use. The content can be related to any of the following: product, organization, industry. Convert this content to appropriate set of Concept/Task/Reference/specialized topics. Similarly, convert all documents to DITA topics. Store all the topics in your topic store. Creating custom DTD and XSL files Although the DTDs and XSLTs provided in the DITA OT is sufficient to render topics into the required output formats, it is compelling to create custom DTDs and XSLTs to implement company defined standards of content organization and presentation. Many companies prefer customization to match their branding and their intended style/format of information offering. Companies prefer specialization to fast-track content analysis, writing, and adoption across the organization and end-users. Need of an expert DITA Consultant Knowing the criticality/importance of the conversion project: Usually it’s triggered by difficulty in product adoption, falling operational efficiency, vision of the big competition ahead, loss in number of customers, loss in market share, or loss in business image of a company. Goals are usually strategic to improve the above mentioned items.
  5. 5. Converting your legacy documents to XML-DITA by Sudhir Subudhi 5 Having observed the risks in a conversion project: Many DITA conversion projects failed in the past due to ineffective implementation. Some got back to their legacy standards after wasting a lot of money and time. Some couldn’t scale up the DITA documentation set to meet their further information needs. Some even backtracked before attempting a conversion. Companies need an expert DITA consultant (internal or external): To provide guidance and support to push through the conversion project through many organizational constraints. To provide guidance and support to design the architecture of the new DITA documentation set. To create and mentor a self-sustainable DITA team to take care of future DITA needs of a company. To create or help creating a set of reusable utilities to help the project team in their future work. To monitor and guide the overall project progress to achieve a fail-proof conversion.