Frame 8 is here: conversion or migration from unstructured FrameMaker to DITA

FrameMaker 8 was released yesterday, with DITA possibility built in, but you will need to do your homework to determine the best path to migrate legacy content from unstructured Frame to DITA. Questions such as Unstructured to DITA – Concise Conversion Information Needed and What are the steps to convert an FM book to DITA To CHM? are consistently appearing on the Adobe Framemaker 7.2 application pack forum. While conversion is part of the migration process, you have to examine your content and get it to a point where it could be converted, so I prefer the term migration to conversion.

I did some research on this topic, attempting a conversion of legacy unstructured Framemaker content to DITA, and wanted to write it up here in case it helps others.

In my experience with Frame 7.2, I wasn’t able to complete the entire complex process, partially due to the unstructured Frame files, partially due to my limitations in getting XSL to work through Framemaker and writing a Framemaker structured application. Feel free to comment on these instructions if you have questions or ideas for where this process may not work well. Note that I haven’t fully studied how this process might change with the introduction of Frame 8, although many of these tips and tricks will still be useful for preparing your content.

Content preparation tips and tricks

If your Frame content is not already written in topics and pretty well structured, work really hard on getting the legacy content into some sort of order that will help in conversion. For example, make each Heading a topic starting point. Next, you may want to type the content into task, concept, reference beforehand using style tags to indicate what type of topic the content is, such as heading1task, heading1concept.

Indicate your task step numbered lists with a different style name from “plain” numbered lists.

Write your abstract and shortdesc (short descriptions) as initial paragraphs of each topic.

Use test Frame files that have few paragraph tags used. Add in paragraph styles one at a time and test the step-by-step process to make debugging easier.

Use a subset of DITA tags for your conversion, meaning you will be converting content to topics with fewer tags than the full DITA tag set. After conversion you can re-tag the content more specifically but having fewer tags to go to means less troubleshooting for the conversion itself.

Performing the conversion

The overall steps for the conversion involve the following tasks:
1. Structure the current unstructured FrameMaker document with the conversion table and rules text file as mapping helpers.
2. Open Frame book file and import the EDD or Element Definition Document, a proprietary FrameMaker file that correlates to a DTD (Document Type Definition).
3. Save the new resulting file as XML, either using a customized migration structured application that applies custom XSLT, or using the DITA Application Plug-In (which is a structured application also).

Each overall step is described in the tasks below.

I’ll also describe the files you’d create to start such a conversion. To create a structured application, you create a new folder in a C:\Program Files\Adobe\FrameMaker7.2\Structure\xml\ directory. This folder contains:

  • A text file that tells FrameMaker what XML means in its own formatting conventions. For example, it tells Frame that the “xref” element is a cross-reference in FrameMaker.
  • A Document Type Definition file that works in concert with the EDD file that FrameMaker needs to interpret the DTD.
  • An Element Definition Document required by FrameMaker. This file is what you import into a FrameMaker chapter file.
  • An XSL file that could transform FrameMaker XML into separate DITA topics rather than maintaining many topics in each chapter file, instead each topic would be in its own file.
  • A structured FrameMaker file containing the configuration information for both the DITA plug-in and the new structured application that could use the XSL file for transformations.

To apply the conversion table

1. Open the Frame book file that has had the EDD imported into each chapter file.
2. Open the conversion table file.
3. Click File->Utilities->Structure Current Document.
4. Select the conversion table file name from the drop-down list, and then click Add Structure.

To apply the EDD

1. Open the Frame book file and select all chapter files using Shift+click.
2. Click File->Import->Element Definitions.
3. Select the EDD file name and click Import.

To save as XML

1. Click File->Choose Structured Application. Select either the trx-migrate structured application or the DITA-Topic-FM structured application.
2. Open the Frame book file and select all chapter files.
3. Click File->Save As and choose XML.
4. If you are using the trx-migrate application, the XSLT would be run on this step. If you are simply saving as DITA XML, then you would choose DITA as the Structured Application from the File menu.

Comments on the conversion table

The conversion table takes existing content and maps each paragraph and character style to an XML element, then wraps the elements in outer elements as needed. To accurately portray the information and ensure that one change doesn’t affect other areas of content, you must modify this table one element at a time and then check for accuracy. The conversion table is a painstaking and time consuming project in itself, depending on the complexity of the content you have to start.

Manual cleanup and DITA map creation

According to this article, you would have additional manual cleanup of graphic importing, copy and paste for all table cell text, creation of cross reference links, and creating the hierarchy for your DITA maps because of the flattened nature of the saving topics at the heading level.

Reading list and references for conversion

7 Comments

  • Pingback: DITA Blog - a group blog for DITA information developers » Blog Archive » FrameMaker 8, now with DITA

  • Pingback: Framemaker and Migrating from Unstructured Content to DITA Structured XML Content @ Structured Framemaker, FDK and XML Blog

  • Sasi Chandru
    October 23, 2007 - 6:55 am | Permalink

    Hello Anne,

    I’ve just browsed through the web site. It’s really worth a visit. The site seems to be documentionally (ding!) exhaustive. It’s pretty complete and advanced as well. Your effort will certainly expand the horizons for technical writing / documentation in days to come.

    You’ll be remembered….

    Keep going….

    Cheers

    Sasi

  • July 28, 2009 - 9:42 am | Permalink

    Hello Anne,

    I agree with Sasi that your blog is extensively documented and easy to search and follow.

    Regarding this article, do you have an example of a conversion table and the file formatting it needs to carry for FrameMaker 8 unstructured conversion to structured only? I am attempting to convert a brief document over, yet retain the master and reference templates. Do I need to convert completely to XML and DITA when my organization is not yet there?

    Best Regards,
    E. Wang

    http://www.tinyurl.com/shesadool

  • July 28, 2009 - 9:45 am | Permalink

    FYI – at the time, were you able to complete the entire process when you converted the initial FrameMaker file to .mif first? Have you used Stilo Migration software process and tool since this article was written?

    Thank you for diligently sharing your experiences and expertise with the technical communications community!

  • July 28, 2009 - 9:36 pm | Permalink

    Hi Emmelyn –
    So glad you’ve found my blog helpful – long time no see!

    Let’s see, I wrote this in mid-2007. I never did complete the entire process. I don’t think Stilo was available at the time. I am searching for the files I had for that particular project, but not finding them immediately. Sorry about that. If I find them I’ll email you.

    You’re pointing out to me that my blog posts don’t have date stamps on them! I need to change that.

    You may want to proceed directly to FrameMaker 9. It has improved DITA support and might make your life easier for a single document.

    Hope this helps!

  • Shail
    December 13, 2009 - 9:00 pm | Permalink

    Hi annegentle,

    Glad to see your article on framemaker to dita conversion. I just got an assignment and started to work on exact same stuff. With Framemaker 9, I was able to easily create a new DITA doc, but it doesn’t have an option to convert an existing .fm unstructured to DITA. If you have, can you please share some samples related to unstructured to dita migration.

    Eagerly awaiting for some help :) and I would really appreciate it.

    Thanks a ton,
    -Shail

  • Leave a Reply