September 2013 Meeting Discussion: Converting FrameMaker Content to DITA

Presented by Scott Prentice, and reviewed by Rebecca Firestone

This presentation by Scott Prentice, founder of Leximation, Inc., http://leximation.com focused on the detailed steps, and pitfalls, of converting unstructured FrameMaker books into structured FrameMaker, and from there all the way to XML/DITA. Prentice has been doing this for over 20 years and has developed his own methodology, which he kindly shared with us, running his Adobe FrameMaker 11 inside VMWare on a Macintosh. (He says it works better than on a PC as long as the Mac has 8 GB of RAM.)

Takeaways

  • Frame to DITA conversion is NOT a simple, one-step process: it’s labor-intensive and requires several sets of tools.
  • Many features of the original Frame books may be lost, especially if you’re using multiple text flows and frames with multiple graphics and text callouts.
  • Any irregularities in the original Frame files will have to be corrected, along with extensive content rewrites to better fit the DITA model. In other words, it’s not for the faint of heart.
  • After conversion, you don’t have to go through it again for the same book–future content revisions are made within the new XML files. (If you open an XML file in FrameMaker, you’re using the “Structured FM” interface, but you’re actually working on XML files.)

Let’s see if I can remember the gory details.

There are actually several methodologies besides the “Conversion Table method” that Prentice demonstrated.Frame to DITA Options

  • Conversion Tables – Lots of short steps, with some automation, a lot of manual fixes at each step, very iterative. Different tools needed at each step, either scripting tools or FrameMaker plug-ins. Benefits are the ability to fix structural problems at each step before going on to the next.
  • Mif2Go – More of a one-step process, but doesn’t have any intermediate points to fix things. “Best if content is rock-solid,” emphasized Prentice.
  • Stilo Migrate – A cloud-based tool that charges by the amount of content converted.
  • WebWorks – Possible, but you need customization and templates, which WebWorks discourages.
  • Consultants – For example, Prentice and Leximation, or others. This might be a good option if you have only a few books to convert.
  • Copy/Paste – Not such a silly idea, since you have to do a lot of rewriting anyway. Not as fast.

So why do we need all these intermediate steps? Well, content is rarely that clean. (Huh. I don’t know about you, but MY content is always perfect…)

Prentice recommended the book Structured Application Developer’s Guide and Reference from Adobe, which is actually two books now: one for Guide and one for Reference. (Not available in print.)

Conversion Table. This is where you map Frame styles to DITA elements, and then “wrap” the elements into sub-assemblies to create ordered lists and groupings of elements. Prentice did a lot to de-mystify this beast, although an hour won’t make anyone an expert.

Content Analysis. Prentice didn’t discuss this at length, but I think this is where a consultant would come in handy, to expedite and guide in this part of the task. Every bit of content, and how it’s structured, must be sanitized with a fine-toothed comb. Whatever you come up with from this step influences the Conversion Table. Getting this part right will save you time later on. Try to have a test file in unstructured Frame that contains every single style tag and content type that you want to have in your converted files.

Prentice didn’t try to gloss over the real work involved in Frame to DITA conversion.

Style overrides will come back to haunt you.Pitfalls

  • Use paragraph and character tags consistently, for one type of content. Don’t use a Figure Caption tag for something that isn’t actually a figure caption.
  • Only the main text flow will export. (I interpret this to mean that anything with a fancy page layout like a newsletter with multiple “continued” flows for several articles is not going to come across well.)
  • Multiple objects and graphics within a single frame are merged. I wish we’d had more time to see this, since it would be interesting to review the resulting image quality.
  • Tabs and line breaks are typically lost, although there are ways to preserve line breaks.
  • Conditional text applied within a paragraph will have problems. Apply C-text at the paragraph level only. May require additional scripting or tools.
  • Cross-references need scripting to work properly, and may need to be gimmicked.
  • Variables turn into entities.
  • Tables are especially fun. Titles end up in the wrong place, and that’s only the start.
  • Each topic needs a unique identifier, which Frame does not handle well for DITA. Requires scripting.
  • Don’t have two subsections named “Overview” in different chapters in your book if you plan to create the XML file names from the headings.
  • Expect a lot of post-processing. Not only cross-references, but image references may need conversion.

Clean up Frame files. Re-apply style tags and rewrite content.Conversion process

  1. Apply conversion tables to Frame book, creating structured Frame files.
  2. Import EDD and a template into structured Frame files and review the resulting redlines. Fix problems.
  3. Clean up structured Frame files using FrameSLT or other similar tool. You will spend a lot of time here.
  4. Export to XML, making one XML file per chapter.
  5. Perform additional cleanup via XSL to “shred” this monster XML into separate files, or use a tool to do the shredding for you.
  6. Open all this XML in structured Frame to validate. Alternatively, you can run it through something like DITA Open Toolkit and “see where it blows up.”

If the above seems too full of jargon, try reading one of Prentice’s blog posts like this one: http://blog.leximation.com/2012/01/framemaker-edd-template-rules-%E2%80%93-what-is-all-that-and-how-does-it-benefit-me/

The rest of the talk was pure demo. Being able to see the results at each step was very useful. It was a bit like a programmer’s walkthrough. Prentice really knows the “gotchas”. It seemed that his process was somewhat idiosyncratic, although I could say the same of a lot of what I do, too. If you want perfect control, you end up tweaking just about everything. A cynical person might suggest that he’s making the process seem harder than it needs to be so that people will hire him instead of trying to do it all themselves – well, I’m all for getting expert help if it means the project actually gets done, and I get to keep my sanity.

So, Should You Drink the Kool-Aid?

I’d probably hire a consultant like Prentice to get me over the hump and act as a coach during the conversion period, but would also try to acquire that expertise myself as we went along. Organizations that don’t have an in-house writer might need to hire an additional contractor who’s already familiar with XML conversion to do a lot of the grunt work.

If we’d had more time, I would have liked to explore a larger question, namely: When is it really worth it to go through all this? What staffing levels and timeframes are realistic to achieve a successful migration? What else is out there? There was a talk a few weeks ago at STC-Berkeley where the presenter said “Oh sure, a solo writer can do it all, without previous experience. . .” Really? I can’t see that happening if the writer is also simultaneously responsible for developing new content, in constant meetings with product developers, etc. . . I began to question the value of the entire exercise, but it’s probably only a matter of time before we’ll all have to start moving in this new direction.

Rebecca Firestone began tech writing in 1988 in Washington, D.C. Highlights include OR/MS topics and software documentation, including telecom/wireless billing and contract work throughout the Bay Area. In addition, Rebecca did a 2-year stint as a software trainer, and several years of design blogging for local Bay Area architects. Outside interests include yoga, Middle Eastern music and dance, circus arts, and fitness. She is currently employed as a Senior Technical Writer at Zep Solar, Inc. in San Rafael, CA.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s