Changing the engine without stopping the car (part 2)

Tuesday, February 26 2013 @ 7:26 AM, By Parth Mukherjee

In the first part of this 2-part article, I explained how mixing structured with unstructured content in the same publication process was vital to the success of several conversion projects I have undertaken in the past years. It is simply not feasible for a company to stop for months while rewriting their legacy documentation or converting all of it before they can start producing publications again.

But even when all of your content has already been converted to well-structured materials, the transition to modern style single-source authoring is not done yet. You will still have to chop your structured content up into topics and import those into some kind of content management system, to make them available for reuse. When producing your output from a CMS, all the topics normally have to be available within that CMS. This is the second hurdle that can be changed into a smooth transition, by using the concept of a repository and postponing the choice of a CMS at least until re-usability has been completely implemented. This second article explains how this was done in a couple of my projects.

Reuse can be realized in various ways. One works on a map level: pulling topics together via some organized list of references, from which the final publication is built. Another method is inserting content that is pulled in from another topic using the concept of a conref. The conref is defined in the DITA standard but similar methods have been available in other areas (e.g. engineering). The idea is that you add a reference to some remote content, but instead of showing the link to the user (as in a cross-reference), a read-only copy of the content is pulled in.

In the project that I am describing, the step from structured content to reused structured content was implemented using FrameMaker and a free plug-in created by West Street Consulting and called InsetPlus. This wonderful piece of free software replaces FrameMaker’s native text inset capability and makes it DITA compliant. The result is an ordered method for pulling content in from another document without invalidating your structure.

Using this plug-in and some ExtendScript, I created a method that takes a selected piece of structured content, asks the user for some metadata, pushes the selected element into a repository for reuse and automatically links it back to where it was. In the end nothing has changed to the content, except the fact that the editable source is now elsewhere, in the repository that is meant to hold content for reuse.


This method does not change the content of the FrameMaker document that I am working on, and thereby keeps the publication process untouched. Whatever the state of the repository is, however many elements have or have not yet been pushed into the repository, output can always be generated from the current state of the document. In a world where sudden deadline changes occur and where unexpected hiccups may cause slower progress than was planned, this ability to produce output at any time is of great value. Imagine having to push back the release date of an already announced product, just because the documentation was not finished in time.

Probably, your company will want to get a component content management system in the end, if only to make the management of reusable documentation easier. Transition from having all reused content available in a structured repository to having everything available in a CCMS is easy, as all items are already treated as separate objects in the repository.


Without smooth transition processes, the step from unstructured monolithic documents to a structured authoring environment that is based on reuse, can be a very costly step in terms of operational cost. By making both phases of this transition available in a manner that does not disrupt the publication chain or depend on the overall status of the elements (unstructured, structured, made available for reuse), the barrier that keeps companies from modernizing their documentation workflow may be practically leveled.

Whether or not the described smooth transition phases can be implemented depends on the technical capabilities and restrictions in the authoring environment. My transition projects have shown that Adobe FrameMaker is perfectly suited for this type of job.

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.


  • Categories

  • Archives

  • Authors

  • Useful Links

  • Recent Comments

    • Mark Carson: Whoops, I meant “on” it…
    • Mark Carson: Sure hope Praveen likes to work on a Mac and wishes FrameMaker was no it.
    • Dieter Gust: Congratulations for a great work done! We finally got several exciting new features. My favorites: 1.)...
    • Maxwell Hoffmann: Hello Paul; I just tried link to video with Chrome and it does work. Try this; clear cache in your...
    • Paul: I could not get this presentation to play. I tried it in both IE and Chrome. It would start to play and get...