Converting your legacy documents to XML-DITA by Sudhir Subudhi

Converting your legacy documents to XML-DITAPrepared by: Sudhir Subudhi, Senior Technical Writer and DITA ConsultantLinkedIn Profile: in.linkedin.com/in/sudhirsubudhiEmail: sudhir.subudhi@outlook.com Skype Name: sudhir.subudhi

IntroductionMany 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

1

Converting your legacy documents to XML-DITA by Sudhir Subudhi

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.

2. Perform audience analysis and task analysis of the product.

2

Converting your legacy documents to XML-DITA by Sudhir Subudhi

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 AnalysisWhile 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-sheetIt’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 ModelThe 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.

3

Converting your legacy documents to XML-DITA by Sudhir Subudhi

Tasks explained in the document

Supporting Concepts Supporting Reference topics and other supported topics to execute the task

Derived/Reusable/structured Information Types or Elements

Starting ABC software

About ABC software Troubleshooting1: Invalid licenseTroubleshooting2: System not respondingFAQ1: What is ABC?FAQ2: Who are the users of ABC?Glossary term1: ABCLogos and Labels for ABC software

TroubleshootingFAQ Glossary term

Task 2Task 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 filesAlthough 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 ConsultantKnowing 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.

Having observed the risks in a conversion project:

4

Converting your legacy documents to XML-DITA by Sudhir Subudhi

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.

5