JoAnn Hackos, Comtech Services, Inc.

Members of the CIDM LinkedIn Group have been sharing their concerns about managing multiple releases of a product. Most recently, we hosted a webinar session in which Tracey Atkinson and Wanda Applegate of Siemens PLM Software, who instigated the LinkedIn discussion, presented their requirements for the capabilities they hope to find in a content management system. We have asked developers of content management systems to provide their solutions in white papers, which we expect to publish on the CIDM website shortly.

Tracey introduced the topic two months ago with the following statement:

“We are a software company and need to support multiple product release versions at the same time. Our writers need to be able to simultaneously work on and edit reused content across different versions of the product documentation and then merge those versions together at a later time. Since this is a typical process for software documentation departments, we are interested in hearing how other companies are solving this problem.”

A complete scenario of the Siemens release management issue is presented here.

Siemens PLM Software—Release Management Scenario

The following scenarios describe the high level requirements for release management:

  • Create and manage branches
  • Concurrent editing
  • Merging
  • Labeling (archive)

Create and manage branches

  1. Project manager decides on the starting point and integrates those files into the new (v1.0) branch. Writers check objects in and out of the branches.
  2. The project manager decides when the next branch is needed. Branches can be created at any point, for example:
    1. The v1.0 tdoc release finishes and the project manager creates the v2.0 branch for that work to start.
    2. The v1.0 courseware is still being worked on in the v1.0 branch.
    3. At some point, the PM creates the v1.1 branch for a tdoc release.
    4. At a later point, the PM creates the v1.2 branch for a tdoc release.

Concurrent editing

  1. Work continues in all 4 branches and writers can concurrently edit the same object in any branch. Each branch contains a unique instance of every object.
    For example:

    1. Courseware Chris checks out a topic 1234.xml in the v1 branch.
    2. At the same time Tdoc Tracey checks out the same topic, 1234.xml in the v2 branch.
    3. Courseware Chris edits the topic for the courseware release.
    4. Tdoc Tracey edits the topic for the tdoc release.
    5. Chris and Tracey check in the 1234.xml and release the deliverables as required.

Merge changes

  1. The project manager decides if and when merges need to take place between branches. For example:
    1. When the v1.0 courseware Wave 1 release is finished, the project manager decides to merge those changes to the v2.0 branch so that the v2.0 courseware work can begin.
    2. The project manager decides how to resolve all files scheduled for the merge. The resolve can be handled in two ways:
      1. Auto-resolve: In most cases, the files will contain no conflicts and can be handled by an automatic resolve.
      2. Interactive resolve: Files that contain conflicts (i.e., the same line of code has been changed) will be flagged as requiring an interactive resolve. The PM will need to contact the writers and make a decision on how to proceed.

Label (archive) a branch

  • The project manager decides when work in a branch has reached a significant milestone and should be labeled.
  • The branch is labeled accordingly, for example, v1.0_tdoc_final.
  • Labels can be accessed later to create branches for re-release of content.

I have long referred to the release management issue as “branch and merge.” In order to support multiple versions of a product in the documentation, we need to “branch” a topic to account for ongoing changes and then “merge” the modified topics back into the mainstream topic as the next product release occurs. When this process is handled manually, often by maintaining multiple versions of a topic, a map, or chapters in a traditional book, the merging is often tedious and time consuming, requiring that the writer or writers examine multiple copies of the document and ensure that some variants are incorporated and others are not.

Liz Fraley correctly points out that the issue of bringing together multiple components that are all developed on their own schedules is an integral part of release management for software. In fact, tools like Subversion and Perforce typically handle the software-build process effectively. Unfortunately, although some information-development groups use these products to manage content, they do not provide the full range of component content management capabilities that we have come to expect in systems designed to handle information rather than software code.

Clearly, traditional conditional processing is inadequate to handle the complex set of changes over an entire information set to support multiple interrelated product lines. Tracey’s group at Siemens includes 100 or so writers who maintain documentation and training for 50+ product lines each with multiple concurrent releases. They localize their deliverables into ten languages. Consequently, they need to manage the releases at a high level, including all objects that go with that release version. They prefer to work at the DITA map level rather than at the level of individual topics.

Raymond Stachowiak describes the issues this way:

“Not too long ago I had a unique user requirement regarding versioning for future versions along with current versions. This company maintained concurrent versions. That is if I am working on version 10, I also keep working on version 9 and may in fact have releases to version 9 after I release version 10 and I want changes done to version 9 also reflected in version 10 text where applicable and vice versa. In many cases, changes for future releases are maintained and updated concurrently with other releases since updates made in one version of a product might be added in another version of a product. A bug I fix in version 10 might also be relevant to a bug in the older version 9, and I might release it as a 9.1 release. The same could happen the other way around so changes in the merging process are not one way in this case.”

Robin LaFontaine describes a possible merge process:

“How would a merge work: Let’s say you have a base document B, then this has been branched and edited (call that E2) and also edited along the main trunk (call that E1). Then you need to merge E1 and E2. You would need to compare all three to understand what is going on, and then show changes B→E1 and B→E2, perhaps as tracked changes, which an editor can then accept or reject. It would need to be fully XML-aware, of course.”

Mark Baker will describe his solution to the “branch and merge” requirement at the Content Management Strategies conference in April. The presentation is called “Managing Linking in Reusable Content with Soft Linking.”

Bill Gearhart and I will lead a panel discussion on the release management dilemma at the conference. Please plan to join us in this interesting discussion. We hope the discussion leads to a robust set of requirements that can assist our component content management developers and best address the solutions.

Dr. JoAnn Hackos is the CIDM Director.