Some Thoughts on Our Experience with Assembling Product Documentation Based on Product Configuration

Recently, we've completed several projects for machinery and aerospace customers. The way they create and deliver content is quite different from what we’ve seen in other industries, so I wanted to share some observations and thoughts.

1. Our customers in aerospace and machinery produce complex products: aircrafts, factory machines, industrial robots, and so on. These products consist of multiple components and modules that may vary for different customers, product modules and flavors. In other words, the product may come in various configurations to different customers. The way to know which configuration a specific customer has is to check the product serial number. This is what uniquely determines a specific product assembly.

2. Usually, each customer receives their own product configuration. So quite often, there are no two identical products. For example, when an aircraft manufacturer sells their aircrafts to airlines, each airline receives this aircraft configured specifically for them. Moreover, chances are that even within the fleet that belongs to the same airline, there won’t be two aircrafts with the same configuration. This means that both customers and maintenance engineers need to have access to the product documentation assembled for a specific serial number.

3. The way the content is profiled is also more complicated. Instead of just specifying to which product or component a piece of content is applicable, our customers define to which combination of configuration parameters it’s applicable. For example, a typical conditional statement may look something like this: “(Component1=installed OR Component2=installed) AND (Software=5.0 OR Software=5.5)”. It’s read: this content is relevant only for those serial numbers (product assemblies) in which either Component 1 or Component 2 is installed while the version of the software is either 5.0 or 5.5. You can't do it with plain DITA conditional attributes and ditaval's.

4. Because the content should contain information about the product configuration, metadata becomes more important than ever. It’s required to find the match between a specific product configuration and the content.

5. All these industries are heavily regulated. Not only the content itself has to be compliant with the government standards and regulations, but also the processes around the content need to meet all these requirements as well. These processes included how the content is reviewed, approved, archived, and published, among many others.

All this means that a solution that we had to provide was required to be capable to do quite a lot of things:

1. A product configuration database should be provided. This is the place where information about individual components and their assemblies is stored. For one customer, the product configuration database was part of DITAToo. In another instance, DITAToo was integrated with a third-party PLM system from which the product configuration was retrieved.

2. A support for complex conditions was required. As you saw in the example above, these conditions may go far beyond what standard DITA offers out-of-the-box. We’ve built a special editor that allowed our customers to build conditional Boolean expressions and validated them against the product configuration database. Another mechanism we’ve built was looking for a match between the conditional statements and information in the configuration database and filtering the content accordingly for publishing and delivery.

3. To accommodate all this information plus data required by the government regulators, a strong metadata support on all content levels was also provided. In some cases, we had to deal with quite complicated dependencies between the metadata fields.

4. Another thing specifically required by the industry regulations was how the content is archived for possible legal investigations and proceedings in case access to an older version of the content is required. Surprisingly, that was actually an easy part because DITAToo could track versions of the content for both individual files and entire publications out-of-the-box.

5. What we extended, though, was an ability to integrate with external systems via APIs and export the content to formats recognized by other systems. DITAToo provided a wide range of APIs, from simple command line interface to C# API to REST API. In one project, we’ve also designed an ability to export content to ATA2300.

If it’s similar to the way you work with your content, please share your experience and thoughts!