Publication Modules

The legacy Knowledge Warehouse system had seven top-level navigation headings, so in order to provide the same top-level navigation in S1000D, it made sense to create a publication module for each heading. Creating the publication modules seemed straightforward as the legacy navigation structure was available as HTML and, by converting this first to XHTML, it was possible to transform the navigation structure into S1000D XML publication modules using XSLT.

Table 8. A word of advice..

Although this was a relatively straightforward task, with the benefit of hindsight copying the existing navigation exactly was not the best decision. It was later discovered that some of the publication modules were so large that it was almost impossible to work with them in an editor. These publication modules had to be split later into multiple smaller publication modules which were then referenced from the top-level publication module, making it a much smaller and more manageable file. Reviewing the number of entries at each level in the structure before the migration began, and restructuring where prudent, would’ve avoided this extra work later.

In order to match the entry in the publication module with the correct data module, a title lookup was used. It soon became apparent that in some cases the lookup was unable to resolve the correct data module as multiple data modules had the same title. Further investigation showed that the reason for this was that the legacy system did not support content re-use and therefore the same document had been copied into multiple locations in the structure as it was needed. On examination it was found that the documents were not always identical, some having been edited and this created inconsistency in the content. This is exactly the kind of situation that S1000D is designed to prevent through module reuse. To resolve the problem a manual effort was needed by authors to merge the content and remove the duplicates prior to running the migration.