Changing the engine without stopping the car (part 2)

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.

Conclusion

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 FrameMaker is perfectly suited for this type of job.