Content Lifecycle Strategies

Maintain and deliver different versions of content by using releases and branches.

Releases

Releases enable you to create non-editable copies, or snapshots, of maps or topics with all dependencies at their current state.

Interface

Note: Depending on your easyDITA configuration, some operations may be restricted to Administrators and users with specific permissions.
Figure 1. Releases Tab

The Releases tab enables you to do the following:

  • Create new releases
  • Deprecate releases
  • Localize releases
  • Branch releases
  • Download releases
  • Publish releases
  • Preview releases

Guidelines

Keep the following guidelines in mind when working with releases:

  • Before creating a release, check the content for errors. You can do that by publishing your content and verifying how the output looks like.
  • Establish a releases naming convention. Once you create a release, you cannot change its title.
  • The resources in releases do not count against your content object limits.

Example

Figure 2. Releases.

The following example shows three releases of a product guide created from the master branch. The releases cannot be edited.

Branches

Branches enable you to create an editable copy of a map with all dependencies in a separate space.

Branches are useful if you want to maintain multiple editable versions of content.
Note: Depending on your easyDITA configuration, some operations may be restricted to Administrators and users with specific permissions.

Branching Tab

Figure 3. Branching Tab

The Branching tab enables you to do the following:

  • Create a branch from a map
  • Merge content from one branch with content in another branch
  • Replace content from one branch with content from another branch

Branch Menu

The Branch drop-down menu enables you to switch the branch that you are working on.
Tip: We recommend using the default master branch to develop the current version of your documentation.
Figure 4. Branch Menu

Topic Merge/Replace Icon

The topic editor enables you to quickly merge/replace a topic from one branch to a topic in another branch.
Note: By default, merging/replacing topics is disabled and the Topic Merge/Replace icon is hidden. To enable this feature, contact a Customer Success Manager.
Figure 5. Topic Merge/Replace icon

History Tab

Merging or replacing branches creates a history entry that enables you to view and restore a file to the former version by using the History tab.

Figure 6. History Tab

Guidelines

Keep the following guidelines in mind when working with branches:

  • Before creating a branch, check the content for errors. You can do that by publishing your content and verifying how the output looks.
  • Establish a branches naming convention. Once you create a branch, you cannot change its name.
  • Designate a person, for example a team leader, who will be responsible for merging and replacing branches.
  • The resources in branches count against your content object limits.

Example

Figure 7. Branches.

In the following example, each branch corresponds with a particular product guide version. The branches can be edited at any point.

Releases and Branches Comparison

Releases and branches have distinct characteristics that you can use in a synergistic relationship.

Table 1. Releases and Branches Characteristics
ReleasesBranches
Non-editableEditable
Good for localization purposesPoor for localization purposes
Good for archival purposesPoor for archival purposes
Good for scheduled deliveryGood for continuous delivery

Content Release Cycle

Our suggested model content release cycle involves releases and branches.

Guidelines

Keep the following guidelines in mind when versioning your content:

  • Develop the current version of your documentation on the “master” branch
  • When the documentation development cycle for a given version is over, create a release for archival purposes
  • Consider branching a past documentation set when it is no longer relevant and requires updating
  • When a branch is no longer needed, remove the branch.

Example

Figure 8. Model Content Release Cycle.
The following example illustrates that the original release of:
  • The “Product 1.0 Guide” was updated twice
  • The “Product 2.0 Guide” was not updated
  • The “Product 3.0 Guide” was updated once

Version Content

We recommend versioning the product documentation by using both branches and releases.

Before you begin, familiarize yourself with the model content release cycle. See Content Release Cycle.
  1. Develop the product documentation on the master branch. See Version Content.
  2. When the product that you document is nearing release, do the following:
    1. Finalize the content development of a map associated with the product.
    2. Test-publish the map and check for errors. See Assign IDs to Topic Elements.
    3. Release the map. See Create a Release.
    4. Publish the final deliverable from the release. See Publish a Release.
      Note: Publishing the final deliverable from a release ensures that any changes on any branch do not affect the deliverable.
  3. On the master branch, develop the documentation for the upcoming product release. See Version Content.
  4. If you want to alter a past documentation release, do the following:
    Note: Altering past documentation releases may be necessary in the following cases:
    • There is a bug in the documentation
    • A past release of a given product is updated and the corresponding documentation is no longer accurate
    1. Create a branch from the release that you want to alter. See Branch a Release.
    2. On the branch that you created in /content-strategies/content-lifecycle#task-2063__substep_j1h_d5z_wkb, edit the content. See Version Content.
      Note: Your edits impacted only the branch that you created in /content-strategies/content-lifecycle#task-2063__substep_j1h_d5z_wkb.
    3. On the branch that you created in /content-strategies/content-lifecycle#task-2063__substep_j1h_d5z_wkb, test-publish the map and check for errors. See Assign IDs to Topic Elements.
    4. On the branch that you created in /content-strategies/content-lifecycle#task-2063__substep_j1h_d5z_wkb, release the map. See Create a Release.
    5. Publish the final deliverable from the altered map release. See Publish a Release.