Have you lost control over which topic versions belongs to which product releases? Is the same type of information floating around in many different topics in the CMS? If the answer is yes, this is the blog post for you, since it suggest a solution, based on almost 15 years of modular documentation experience, for effective release management.

R&D departments are constantly developing new technical products and at the same time updating released products, where certain functionality is reused across all ongoing developments. Documentation departments must be on their toes to identify which topics to reuse and modify to keep product documentation up to date. It is sometimes difficult to find out which topics are affected by a certain product update. And, since products are developed in parallel, it often happens that the same topic(s) must be edited in parallel in multiple projects. As a result, a topic is often copied or branched, since many user documentation organizations do not want to have the same topic “under construction” in multiple projects at the same time. This means that the amount of topics to manage is growing at an alarming rate.

Many technical communicators, working in a modularized environment, feel uncertain about how to do when a manual must be revised due to that the product is being updated. Especially when there are several documentation projects ongoing in parallel. Which topics are affected by the update? How do I identify them? Do I dare to update the topic if it is reused in another manual for another product configuration? An existing topic, in need of being updated in many projects at the same time, is often copied or branched. “It makes me feel safer and it reduces uncertainty – I don’t want to cause any problems to the sibling projects”.

So, what factors are causing the need to update a topic in a certain project and how can these factors be brought to the surface for user documentation projects? Many technical communication organizations lack a robust framework that holds copied or branched topics together, resulting in difficulties to know how topics relate to each other. But why is a topic used in many projects and how come one project wants to update the topic and the other does not? What are the underlying factors that cause this to happen? To answer these questions we need to look at how R&D product development projects are managing concurrent configurations and releases.

R&D departments can run projects in parallel, developing slightly different product configurations without messing things up, because products are modularized. Most technical products (software applications, industrial machines, consumer gadgets etc) are built up from an integration of hardware and software components (also called modules, functions etc – from now on I refer to them as product components). Each product component has an individual life cycle, and the life cycle versions are usually managed in a configuration and release management system such as a PDM or PLM system (using a kind of object oriented approach). A product component can have a unique identity (part number etc), be related to other components (child/parent etc) and have siblings. A specific version of a product component can be included in several product variant or configuration baselines. Thus a product component can be reused across multiple products.

To get control over the release management processes, meaning to be able to effectively manage documentation for multiple product configurations, released in parallel, you need to make the product components a firm part of you documentation process. The information given in a (DITA) topic is always implicitly or explicitly related to one or many product component(s), so in practice, this means that every DITA topic must be stamped with metadata that corresponds to the product component(s) it is treating or valid for. This approach gives you a lot of benefits. How? Stay tuned.

But first, what does “related to” mean? In some cases, the topic is actually describing the product component from various angels, such as technical data etc. Then the product components is treated in text as “The hardware module X has…”. But most topics are not describing the related product component literally. Product components can be divided into different types; there are for example internal software or hardware components, not visible to the user, and interface component, visible to the user. An internal product component provides certain possibilities and when the user is performing a certain task, the product component is invoked to enable the functionality. In other words, the text in a topic is introducing a task or giving a conceptual description that does not apply if the related product component was removed from the product.

The relation between a topic and product components can be established via topic prolog metadata, internal CMS system metadata or using an external classification system such as for example the new subject scheme feature in DITA 1.2. A topic can be related to several product components and a product component can be related to several topics. Furthermore a product component can often have variants (sibling components with a common denominator) and one (1) topic can be related to several variants where you conditionalize the topic to mark up the specifics to each product component variant.

An important issue is to make the product components “come alive” in your CMS; to implement a metadata strategy that enables you to manage the product components throughout their lifecycle and the relations to the corresponding topics. Today, a product component is most often scattered across a CMS as folder names, system metadata, DITA XML metadata, condition values for filtering etc. This is because most CMS lack a robust support for managing product components.

The following example gives you an idea of a product component oriented documentation approach. The technical communicator must have certain product domain knowledge to be able to identify the product component(s) a topic is related to. In some cases it is pretty obvious, in some other case it is not.

Product 123 version 1.0 is built up from product (software) components X v1.0, Y v1.0 and Z v1.0. You have four DITA topics (all version 1.0 in your CMS), one related to product 123 itself and three related to product components X, Y and Z. All topics for product 123 are approved and frozen in the CMS since product 123 is released and launched to the market. The following table depicts the situation.

Note that the complete product 123 is also seen as a product component. Concept topic A version 1.0 describes product 123 from a conceptual perspective and includes, among many, a description such as “Product 123 is used to optimize processes 123”.

Later on your company starts to develop a new product, called product 567 version 1.0. Product 567 is very similar to product 123. Product 567 is built up from product components X v1.0, and product component Y, which is updated to a v1.1 since a new UI dialog is introduced, and a new product component R v1.0. Product component R is a sibling to product component Z which is not used in product 567. Product component Z and R are 90% the same.

Since you know which product components are used in both product 567 and product 123, you can identify the topics to reuse from the topic relation. Existing topics for product 123 are reused in manual for product 567 (with updates according to table 2).

The text in concept topic A version 1.0 is valid for product 567 except for some minor parts. Instead of copying or branching topic A version 1.0 you create a new version (2.0) of topic A and add a new text, valid only for product 567 using a condition. The new text lives along with the previous text which is also conditionalized specifically for product 123. The new text for product 567 is something like “Product 567 is used to optimize processes 567”. In topic A version 2.0, you also corrected a spelling error. Concept topic A version 2.0 is now valid for and related to both product 123 and 567 (both version 1.0).

You need to create a new version (2.0) of topic C, related to product component Y v1.1, since product component Y is updated (a new UI dialog was introduced) which has to be reflected in text. In this case you are not using conditions to mark up the change. Topic C version 2.0 is not backward compatible, meaning that you cannot use topic C version 2.0 for product 123 version 1.0 since it includes product component Y version 1.0.

The text in concept topic D version 1.0 is valid for product component R v1.0 except for some minor parts. Instead of copying or branching topic D version 1.0 you create a new version (2.0) of topic D and add a new text, valid only for product component R using a condition. The new text lives along with the previous text which is also conditionalized specifically for product component Z v1.0. The new text for product component R is something like “In dialog AB, select item BCD”. The text “In dialog BA, select item EFG” is specific for product component Z and thus conditionalized. Concept topic D version 2.0 is now valid for and related to both product component Z and product component R (both version 1.0).

Your company is also doing a maintenance release of product 123 (to version 1.1) in parallel to developing product 567. So you need to also update the documentation for product 123 in parallel to developing documentation for product 567. Product component Y version 1.1 is now also used in product 123. From the topic relation you decide that:

Topic A version 2.0 is used for product 123 since a spelling error was corrected. Topic B version 1.0 is used since there are no change done for product component X. Topic C version 2.0 is related to product component Y v1.1, which is now also used in product 123, thus topic C version 2.0 is used. Topic D version 2.0 is used, since when filtered, topic D version 2.0 looks exactly the same as version 1.0.

A product component approach gives you many benefits. First of all, it reduces uncertainty. When a product is being updated you know exactly which topics are affected. Furthermore, sibling projects can benefit from general updates, when for example corrections are made in one project, such as correcting a spelling error. If your products include optional functionality, you can filter out all topics related to product components not purchased by a certain customer. This enables you to create order specific documentation. Furthermore, the product component relation allows you and your fellow technical communicators, as well as the end user, to find all topics related to a certain product component. To retrieve all topics for a certain product components gives many benefits, among many from an information ownership perspective. Many SMEs are responsible for a certain set of product components, and they often want all information related to a product component (to review it etc). 

My experience after using this approach for almost 15 years, is that there are a number of aspects that must be addressed before implementing a product component way of working. How do you conditionalize topics, meaning what type of condition values do you use (product or product component values - and if you use product components as the conditioning values - how do you manage the values throughout the life cycle of the component)? Will this approach affect the information architecture, in a sense where it becomes more product and feature oriented? How do you manage topics related to several product configurations, as product components can be removed or included throughout the product configuration lifecycle? When and how do you relate a topic to several variant product components? When and how do you relate a topic to several product components that are not variants? How do you relate task topics to product components?

SeSAM, a design methodology for technical communicators, includes a product component strategy that answers the above aspects. Contact Jonatan if you are interested in knowing more.