Changing the engine without stopping the car (part 1)

Monday, February 11 2013 @ 12:54 PM, By Parth Mukherjee

Even if it is crystal clear that structured authoring has many advantages, many companies cannot afford to make the jump into the new paradigm. There is too much legacy documentation that cannot be left behind, and there is never time enough to stop all the presses for months while the old content is being converted and imported into a content management system. This blog post explains the basic methods that were used to overcome this problem.

codieOver the past years, I have helped several customers to make a smooth transition. This was possible by using some of FrameMaker’s unique capabilities. The most important of these is that FrameMaker books can contain both stuctured and unstructured files. Instead of having to convert all content in one go, we were able to tackle the chapters one by one, never endangering the publication process and always able to publish books, whatever the stage they were in (as far as converting to structured content is concerned).

Chapters with a lot of edits were converted first. This means that authors were correcting the structure (almost always required after an automatic conversion) and augmenting the content at the same time. This not only made the process more efficient but also got the authors to understand the required structural changes better, as they were already revising the content and finding ways to improve it with the new structure in place. Chapters that contain legacy information but require no editing were left for last. By that time, the authors were very well used to the structure.

As an extra advantage, this phased conversion of legacy content enabled us to gradually improve the conversion tables and scripts that were used to automate the conversion work as much as possible. Insights from the first couple of chapters were instrumental in smoothing the process for subsequent materials.

The fact that FrameMaker can deal with mixed structured / unstructured content sets this product apart from most other structured editing environments. Each FrameMaker file can be approached as an unstructured as well as a structured file. The structure that is added in the conversion process adds an extra layer that is interwoven with the already existing content and formatting. In technical terms, the current cursor position is always both a text location (handling the file from the unstructured viewpoint) and an element location (handling the file as a structured collection of elements).

This may seem like an unimportant implementation detail, but in smooth transitions to structured authoring it is of paramount importance: the publication process does not change when adding structure to one or more components of a book. The very same publication engine simply churns out your PDF (or other content using various plug-ins), simply working away at the files from the unstructured viewpoint. The content has formatting applied, but whether that formatting is derived from the structure or implemented manually via paragraph and character format tags, is completely irrelevant to the end result.

In the next blog post, I will explain the next step in the transition, bringing in reuse elements – again without ever stopping the publication process. That premise has been the basis for success in the smooth conversion processes I have undertaken in the past years. Instead of the well-known ‘Never change a running system’ I can now offer my alternative: ‘Why would change have to stop the system from running ?’ or, to use a real-world metaphor: Change the engine without stopping the car.

About the author

Jang Graat headshotJang 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.

COMMENTS

  • Categories

  • Archives

  • Authors

  • Useful Links

  • Recent Comments

    • Joel: Thanks for fixing the links guys!
    • Maxwell Hoffmann: Ted, one aspect of the blog that may have escaped your notice; you can launch the HTML5 version in...
    • Maxwell Hoffmann: Joel, per comments made above, I discovered that the original URLs were incorrect with pointers to...
    • Maxwell Hoffmann: Paul, as I indicated in the comments below, the original blog had links that pointed to a...
    • Maxwell Hoffmann: I apologize to all concerned regarding my suggestion to “clear the cache” … it...