Working on multiple documentation versions in parallel

Branching and updating previous versions allow you to work on multiple documentation versions in parallel.

When you need to work on a new documentation version that is based on an existing version, you can clone the documentation set used in that version. This allows you to use the existing content as a starting point for the next version.

When you clone an existing version, the DITA CMS creates a new container and automatically branches all the maps in that version. For each existing map, it creates a new version of the map with the same content as the source version.

The following diagram shows how the DITA CMS handles maps when branching a documentation set. In this diagram, when MapA in Version 1 is branched to Version 2, the DITA CMS creates a new version of the map and this map references the Version 2 container. At this point, the Version 2 container references the same content objects as in Version 1, as shown in the example below:
Branching, phase 1

The new version automatically reuses all the content objects from its source version. At this point, changes made in Version 1 are automatically propagated to Version 2.

Important note

Topics, images, and resources can be reused in multiple versions inside a single product or library, but you cannot use the same map in multiple versions. When you add a map to another version, the DITA CMS creates a new version of this map, which references another container. The topics, images, and resources that the map contains can be reused in other versions, but each map version is used in a single version.

Writers make the changes for Version 2 in the new map version. They can edit existing topics by branching them, they can add new ones, and they can also remove unnecessary ones, without impacting the source version. For example, the following diagram shows that Task 1 was branched: The DITA CMS has created a new version of Task1 (Task1 v2) and updated Container_v2 so that KeyB now references Task1 v2. Changes made to Task1 v2 will not be applied to Task1 v1.

In the example below, a new concept was also added in Version 2. Version 2 will continue to use the same Concept1, Task2, and Task3 as Version 1, which means that any change made to these objects in Version 1 will be propagated to Version 2, and vice versa.
Branching, phase 2

Updating to previous versions

You can apply changes made in a new document version back to another version. For example, let's say that version 2 of Task1 should also be applied to version 1 (MapA v1). You then simply update version 2 of Task1 to version 1, as shown below:

When version 2 of Task1 is updated to version 1, the DITA CMS updates Container_v1 so that KeyB now references Version 2 of the topic.