In conversion projects, time is often the limiting factor. Even if you really feel the entire 500-page manual should be converted to DITA or some other structure, you might be stuck with the old materials for a long time to come. And while you are hacking away at the old document, changing details in the specs that must comply with the current state of your software, you cannot shake the idea of wasting time on a product that has no future. In one such project, a customer asked if they could keep the free-text sections of their documentation but replace the formal sections with auto-generated DITA content. This is how we are tackling the problem. It shows once more that FrameMaker is a wonderful environment to work in, allowing any crazy kind of mixture my crazy mind comes up with.
The original idea of the customer was breaking the 500-page long document up into a hierarchy of books, with each book containing the auto-generated DITA file for the formal API description and the remaining free-flow unstructured content of the old documentation in a second file. Combine all those two-chapter books together into one single book and you have the full document.
In itself, this approach would work, but there would be a lot of hassle with the many cross-references that are present in the free-flow text sections that remain part of the new book. So I set out to run some tests and found out a little more about the manner in which FrameMaker treats structured documents. In fact, FrameMaker is a little like Dr Jekyll and Mr Hide. The same program can look at the same document from two different viewpoints. When looking at any document in unstructured mode, Frame sees paragraphs and formats. It overlooks anything that points to structure. And then, when looking at the exact same document in structured mode, all of a sudden the element boundaries appear and Frame can traverse the structured object tree from the highest level element down to the smallest leaves.
This split mind of FrameMaker gave me the incentive to test another approach to the problem of my customer. I used text insets to pull a DITA file into an unstructured document. Guess what? Frame does not care about all that structure in the DITA file and simply puts the content into the unstructured document. No problem at all. From the unstructured Frame point of view, the content is simply formatted text. The structure layer does not bother Frame at all.
After running this simple test, the solution for this particular customer became a simple automated search and replace operation, implemented in an ExtendScript: find each API module name, remove the sections that contain the formal description, and insert a text inset pointing to an auto-generated DITA file. To make the content from the DITA file comply with the formatting in the remaining unstructured sections of the full-length document, the read-write rules were adapted (as some auto-generated DITA elements were not needed) and the template for DITA import (which defines the formatting of the DITA elements) was adapted. No XSLT needed.
In the end, the free-flow descriptions of the API modules, which remains more or less the same across many releases of the software product, did not require conversion to DITA. Only the formal sections, which have to be 100 percent correct and compliant to the release of the software, are automatically generated and can be updated without even looking at the result in the full document. Updating all text insets does the trick.
Without an editing environment that happily combines structured with unstructured content without breaking the publication process or even making it hard to do, this project would not have been possible in the couple of days that were budgeted for it.
About the author
Jang F.M. Graat has studied Physics, Psychology and Philosophy, before starting a career in the high-performance computer industry. He has more than 25 years experience in technical authoring, training and consulting and runs his own consulting company in Amsterdam, Netherlands. In the past 10 years, he has been working almost exclusively in FrameMaker, recently adding FrameScript, ExtendScript and XSLT to his portfolio. He is a well-known and popular speaker at conferences and maintains a series of blogs on Automating FrameMaker on his website.