Migrating from a CCMS

I've never needed a roadmap for any documentation migration project; my experience has been that content, if reasonable well-formed and well-styled, is easy enough to import into commercial tools. But I had never tried to push content back "upstream", to the friendly formats we now need for Agile collaboration: indeed, I’ve yet to meet anyone who worked to take content out of a component content management system (CCMS), having gotten it there!

And just as with moving houses, the longer you’ve lived in a CCMS, the harder it is to pack it all up, if you aren't porting to similar formats and granularity. Here are some of the tasks it required, to get us out of the CCMS:

1. Unraveled the reuse of objects so that they each occur only once in the export file set.
   This is not as horrifying and counter-productive as it sounds, for much of the reuse would simply be reimplemented in the new system; the trick is to bring over each bit of content only once. Reuse spanned the entire library, of course: books within books, topics within topics, graphics across topics. What saved us was the discipline of reserving 99% of reuse to books within books (my take on Reusable Learning Objects) and rewriting content to support that multi-context reuse.
2. Exposed all hidden notes/references/commentary/history (designed to never publish) so that it’s included in the export files and not lost.
3. Optimized object templates (such as link formatting and style assignments) for how D2H interprets files on import.
4. Wrote Word macros to achieve reproducible post-processing: resizing graphics, substituting styles, converting to Word XML (DOCX), etc.
5. Created export projects and batch files to automate the migration so we could iterate.

This last point proved to be the crucial factor, because speed of conversion R&D increased dramatically once I could kick off a new export/import/build batch to test each new theory of how to solve a problem or transform a content feature. And that is a lesson that generalizes to everything I face in documentation architecture: automation always pays.