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 with all dependencies at their current state.

Interface

The Releases tab enables you to manage all aspects of maps releases.

Note: Depending on your easyDITA configurations, some operations may be restricted to Administrators and users with specific permissions.

The Releases tab enables you to do the following:

• Create new releases
• Localize releases
• Publish releases
• Branch releases
• Preview releases
• Download releases
• Deprecate (or archive) 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.
• 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

Branches

Branches enable you to create an editable copy of a map with all dependencies in a separate space. They are useful if you want to maintain multiple editable versions of content.

Interface

The Branching tab enables you to manage content in separate spaces.

Note: Depending on your easyDITA configurations, some operations may be restricted to Administrators and users with specific permissions.

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
• Compare branches

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

The Branch drop-down menu enables you to switch the branch that you are working on.

Tip: For most use-cases, we recommend using the default master branch to develop the current version of your documentation.

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

Releases and Branches Comparison

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

Table 1. Releases and Branches Characteristics

Releases	Branches
Non-editable	Editable
Good for localization purposes	Poor for localization purposes
Good for archival purposes	Poor for archival purposes
Good for scheduled delivery	Good 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

Example

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. User GuideSee Create.

   
   

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. User GuideSee Publish Maps or Topics.
   3. Release the map. User GuideSee Create a Release.
   4. Publish the final deliverable from the release. User GuideSee 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. User GuideSee Create.

   
   

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. User GuideSee Branch a Release.
   2. On the branch that you created in 2, edit the content. User GuideSee Create.
      Note: Your edits impacted only the branch that you created in 2.
   3. On the branch that you created in 2, test-publish the map and check for errors. User GuideSee Publish Maps or Topics.
   4. On the branch that you created in 2, release the map. User GuideSee Create a Release.
   5. Publish the final deliverable from the altered map release. User GuideSee Publish a Release.

User Guide