This article will cover (briefly!):

• Choosing your content set pragmatically
• Issues with Converting to DITA (focus on FrameMaker and Word)
• Balancing legacy with converted content

Choosing your content set pragmatically

… the migration to DITA has been a gradual one that has not started out with full adoption of all principals of modular authoring.

For those companies we've worked with at Mekon, the migration to DITA has been a gradual one that has not started out with full adoption of all principals of modular authoring. Many will convert their unstructured content to large nested topics that replicate the originals. This is sometimes just 'the way it has to be'.

A lot of people see 'project scoping' as overhead that delays 'production', but it's a classic example of 'measure twice, cut once'

Success often comes from scoping your project properly. A lot of people see 'project scoping' as overhead that delays 'production', but it's a classic example of 'measure twice, cut once'. Large organisations with recent growth and acquisitions should measure several times! Select a first docset that is in every way 'middle ground." i.e. one that is a good example of your most likely documents to be converted. Here are some do's and don'ts to guide you in choosing your first docset.

• Do NOT use your biggest, baddest, most complex docs. Capture the majority of the content in automation; don't deal with every weird edge case.
• Do NOT choose 'flagship' products or upcoming 'secret weapons' for your first project. If there are management microscopes on your efforts, even reasonable acceptable setbacks could scuttle your entire initiative.
• DO choose a representative sampling from various docs/teams to work out metadata and reuse strategies, before converting. DITA implies new top-level organisational structures and metadata which you don't want to have to apply retrospectively. This will also affect a new CMS, style sheets, etc...
• DO prototype your conversions. Seeing some output always helps perfect the conversion spec.

Issues with Converting to DITA

Inconsistent formats in source documents make conversion processes fail more often than not, thus requiring more manual fixing. Here are some of the issues that my colleagues and I at Mekon have found in the work we have done for clients that might help you assess your situation and more accurately project costs and timelines.

Conversion of existing unstructured documents to anything other than a basic DITA topic is more difficult to achieve due to the restructuring of content that would be required to fit in the specialised DTDs. For example, companies might have something that is essentially a task, but the formatting in the unstructured documents does not match the DTD. For instance there might be a different structural nesting of the content, or it might contain their own very specific formatting, which is meaningful for them but has no convenient DITA equivalent. Thus, removing the formatting without mapping it to a new DITA element would mean loosing metadata.

… we have written "clean up" macros in Microsoft Word to ensure that the source documents comply with a given set of rules.

As a solution to the nesting problem, Mekon has worked on a number of projects where we have written "clean up" macros in Microsoft Word to ensure that the source documents comply with a given set of rules. Conversion success is then much higher and in some cases can be 100%. You should investigate what skills/budget is available for this.

Adobe FrameMaker Conversion Tables have several limitations that mean supporting each specialisation is not possible automatically. They do not support actual scripting logic and have inherent issues like the fact that Context Rules in the Conversion Tables cannot apply to more than one instance. Therefore an unstructured chapter that has a mix of task concept and reference could not be converted into the appropriate DITA DTDs. We have tried several approaches to resolve this without a lot of success, so you'll want to check for this. The best solution found was to map everything to the base DITA elements and apply DITA specialised attributes to those elements.

Balancing Legacy Content with New

In most projects, you will have to convert a portion of your content set, and somewhere, something will be sharing content with your new shiny DITA files / CMS system, but will be in the old format. This is a very tough one to generalise, but as a guideline: the older version is king.

If you have a high level of automation, leverage it.

It seems counter-intuitive to focus on the legacy copy. However, you've got a conversion process that runs in one direction only. Therefore, updating the old source and then reconverting and tweaking as necessary will usually give better results. If the changes are minor (<5-10% depending on size of topics) consider just doing them manually in both the legacy and DITA instance, but obviously this is more error prone. The decision should be made based on how good your conversion process is. If you have a high level of automation, leverage it.

In short, the unfortunate truth is that planning your conversion is always helpful, and should be part of your overall content strategy review. If you've any questions, I'm always happy to discuss!

DCLnews Editorial
May 2008