Aligning Changes in the Product with Updates in Technical Documentation

In 2018 and 2019, two deadly crashes of Boeing 737 MAX killed 346 people. The investigation found that both crashes were related to a new system called Maneuvering Characteristics Augmentation System, or MCAS for short. Although MCAS was a new system, it wasn’t properly documented making pilots unaware of how it works and affects the aircraft behavior.

While it seems that not including MCAS into the aircraft documentation was a political decision, it still raise a very serious question: how can you make sure, especially when it comes to complex products with so many components and dependencies between them, that any modification done into any of these components is actually documented and communicated to the customer?

My previous posts explained that an applicability expression defines to which configurations a piece of content is applicable. For example, a piece of content may be profiled using a conditional expression such as “This content is applicable to any configuration with (Component A AND Component C)“. By matching this statement to the configuration database, the publishing engine can find the configurations that include both Component A and Component B, and if you are creating a publication for one of those configurations, the content in question will be selected for the publication.

Modifications can be done both in a specific configuration and in a certain component. For example, if a component is software, it can be upgraded, but only in a specific product configuration. The way to capture the change is to have a database of modifications known as modifications database.

A modifications database typically includes:

• Modification code name.
• Type or category of the modification.
• Affected configurations.
• System in which the modification was done.
• In regulated industries, it may also include references to approvals issued by authorities.
• Other reference information, such as date, descriptions, and so on.

For our purposes, two most important things to notice are affected configurations and the system where the modification was done. Now in the configuration database we have components, and which components each configuration has. The modifications database takes one step further and tells us what modifications were introduced into each configuration.

On the content’s side, we have applicability expressions that refer to configurations. First of all, we can now add even more flexibility to applicability expressions by adding modifications as an applicability condition. For example, a piece of content should be selected not only when both Component A and Component B are present, but also when the configuration has a certain modification. That is, if you are publishing for a configuration that includes Component A and Component B, but does not have the modification in question, this content will not be included.

In this figure, Topic 1 matches Configuration 1, Topic 2 matches configuration 2:

Second, because the affected system is part of the content metadata, by knowing the affected system, we are getting a way to find the corresponding pieces of content to be updated. For our aircraft making customer, for example, we’ve built a feature that checked for every modification, whether a corresponding change was made in the content. If no change was found (or if no content at all was found), the aircraft manual was not released for an official publication.

In this figure, Topic 1 has to be updated because its applicability matches Configuration 1, and its metadata refers to the same system as the affected one. Topic 2 doesn’t require the update because while it’s also applicable to Configuration 1, it describes a different system (this is a oversimplified example, of course, because in the reality, System DDD and System ABC might depend on each other; in this case, this dependency should be also reflected in the configuration database and matched to the content via the metadata):

Moreover, we were able to capture changes done in the content on a granular level. For instance, if a paragraph was updated to reflect a change done in a certain system, DITAToo had a way to associate that particular paragraph with the modification. That was doable, of course, because all the content was in a structured format, and DITAToo could manage it on the level of individual elements within a topic.

This is when a combination of a configuration and modification databases, structured content, and metadata came out in a full strength.

In my next post, I’ll discuss various structured content formats and try to answer the question if DITA is a must have or it can be another structured content format to be able to automate your content process.