How to Handle Cross-References in Automatically Assembled Documentation

In the previous posts, I discussed how the technical documentation in aerospace and machinery companies is different and how a configuration database can enable automated assembly of product documentation.

Today, I want to talk about the challenges that you have to cope with when the content is assembled dynamically. One of them is handling cross-references. Because pieces of content (let’s follow the DITA terminology and call them topics) are filtered differently for different product configurations, there is no a reliable way to know whether the referencing and the referenced topics will be both included into a publication for a specific configuration.

Here’s a case that occurs in aircraft documentation very often (and not just there, I believe).

Suppose a component that should be documented differently for different configurations. Let’s assume that it may appear in three configurations and thus, we have three different topics with different content about the component. Let’s call them Target Topic A, Target Topic B, and Target Topic C. 

Now we have a generic topic (source topic), which is common for all configurations. This source topic references the target topic about the component.

But which of them? Depending on the aircraft configuration we want to create a publication for, that generic topic should reference either Target Topic A, Target Topic B, or Target Topic C. How can we add a generic reference that would be resolved to a reference to the required target topic at the publishing stage?

In DITA, you can use a mechanism known as key references. In the map, you assign an alias called key, to the target topic. In the source topic, when you add a reference, you refer to that alias instead of the real file name. The reference to the alias is configuration independent. If you have separate maps for different product configurations, in each map the same key is resolved to a different file name. If you have a single map for all product configurations, you add all target topics with the same key and profile them. In this case, only one target topic would stay in the map during the filtering and publication stage.

In ATA2300 which is the standard used for documenting flight operations, there’s a similar mechanism called containers. In the example above, a container would include Target Topic A, Target Topic B, and Target Topic C. In the ATA2300 terminology, they would be called alternate Document Modules (DMs). Unlike DITA, ATA2300 defines very clear formal rules on which DMs can be considered alternate: they must share the same ID (or more precisely, a certain part of the ID) by which they can be recognized as describing the same component.

In the source topic, you would add a reference to the container, which is configuration independent. During publishing, all DMs irrelevant for the required aircraft configuration would be filtered out, and only one DM would remain in the container.

In the special edition of our DITAToo DITA CMS designed for the needs of the aerospace industry, we had to provide compatibility and support with ATA2300 while using DITA as the underlying content architecture. So we’ve implemented the ATA2300’s mechanism of containers using DITA’s key references with some tweaks. Now authors who document flight operations can use configuration independent references that become configuration specific during the publishing process.