After posting the recent post about assembling product documentation based on product configuration, I’ve got quite a few requests asking to explain what the configuration database exactly is and how it may help in automating the process of assembling technical documentation for complex products.
Let’s consider a traditional way to profile (conditionalize) content in technical documentation. The way you probably got used to profile content is to set a conditional attribute, such as audience or product, to a value representing an audience, product, release, platform, etc. Then on publishing, everything labeled with a certain product will be included into the publication, and everything else will be excluded. Of course, you can also combine multiple attributes to define that the content should appear only in a publication for a release of a certain product for a certain audience.
However, when you are dealing with a complex product (like an aircraft, industrial vehicle, or factory machine) that comprises of multiple components, these components may be assembled differently into different product configurations based, for example, on a customer's order. In this case, the approach to content profiling needs to be different. The traditional approach won’t work here because the “product” now means a specific combination of components, and your content is profiled by these components rather than by the product itself.
This means you should be able to specify which configuration you want to get, and then all pieces of content that match this configuration would be included into the publication.
Suppose, for example, that the product has several possible configurations (in some companies, each configuration means a different product serial number):
Configuration 1 includes:
Component A
Component B
Component C
Configuration 2 includes:
Component B
Component D
Component E
Configuration 3 includes:
Component A
Component C
Component D
(Needless to say that new configurations that involve more components or/and different combinations of the same components are released all the time.)
Provided that the content is labeled by these components, we need to be able to say that we want to create a publication for Configuration 2, and get the content labeled with "Component B", "Component D", and "Component E" to be included into the publication.
This is when a configuration database comes into the play. The configuration database can be built-into DITAToo DITA CMS or can be part of an external system, such as a PLM or PIM system. Essentially, it contains information about which components are included into each configuration. When you specify for which configuration you want to create a publication, DITAToo retrieves the list of the relevant components, picks up the content labeled with these components, and puts them together into a publication.
To add one more level of complexity we have to deal with, suppose that the content can't be always directly labeled as applicable to "Component A" or "Component B". Instead, the profiling describes the configuration to which the content is applicable as a certain combination of components. 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)".
In the example above, this content would be applicable only to Configuration 1 and Configuration 3 because both of them include these two components.
Similarly, an expression, like this:
"This content is applicable to any configuration with (Component A AND Component C AND Component D)"
would mean the content labeled this way would be applicable to Configuration 3 only.
So if you publish for Configuration 3, DITAToo would retrieve the content labeled with "Component A" AND "Component C" plus the content labeled with "Component A" AND "Component C" AND "Component D".
In the real world, these expressions can be very complicated and also include NOT, OR, and other Boolean statements.
This approach gives quite a lot of flexibility because allows the author to define content applicability based on functional dependencies between the product components.
This is a level of complexity we’ve been seeing in aerospace, machinery, and pharmaceutical industries. While DITA as a structured content standard provides a solid infrastructure necessary for this kind of content personalization, the existing DITA’s content filtering mechanism alone isn’t sufficient for handling this level of complexity. And this is what we do with our DITAToo DITA CMS.
Do you have any questions or would like to share your experience with assembling technical documentation for complex products? Let me now!