Release management domain

The release management domain provides markup that enables content developers to log information about changes that have been made to a DITA topic or map. This information can be used to generate release notes, which can help users locate significant changes in revisions of large documents.

Processors can gather the information and assemble it into an appendix or separate document, thus eliminating the need for separate release-note topics or external tracking mechanisms such as spread sheets or databases. Regulated industries can use the release management domain to provide the records that are required by regulatory agencies.

This figure shows the structure of the release management elements.

Tree structure diagram showing the elements available in the release management domain, their relationships to each other, and where they can be used in a DITA topic. The change-historylist element can appear in the prolog and can contain change-items. The following elements are children of change-item: change-person, change-organization, change-revisionid, change-request-reference, change-started, change-summary, data. The change-request-reference element can have children change-request-system and change-request-id. — Figure 1. Release management elements

The following list provides a brief description of the element:

<change-historylist>: Contains <change-item> elements, each of which represents a release note, which is information about a single change
<change-item>: Contains information about a release note
<change-person>: Contains the name of a person who made the change
<change-organization>: Contains the name of the organization that requested the change
<change-revisionid>: Contains an identifier that is associated with the change
<change-request-reference>: Contains information that provides traceablity to an external change request or other ticketing system
<change-request-system>: Contains the name of the external system that is referenced
<change-request-id>: Contains an identifier that is associated with the change request, such as an issue ID or ticket number
<change-started>: Contains a string that holds date and time information about when the change was started
<change-completed>: Contains a string that holds date and time information about when the change was finished
<change-summary>: Contains a descriptive summary of the change

Example

This figure shows three simple change-items added to a single topic. This topic is used in documentation for two products, A and B.

Figure 2. Excerpt from topic prolog


<prolog>
<!--...-->
  <change-historylist>
    <change-item product="productA productB">
      <change-person>Joan Smith</change-person>
      <change-completed>2013-03-23</change-completed>
      <change-summary>Made change 1 to both products</change-summary>
      <data>Details of change 1</data>
    </change-item>
    <change-item product="productA">
      <change-person>Bill Carter</change-person>
      <change-completed>2013-06-07</change-completed>
      <change-summary>Made change 2 to product A</change-summary>
      <data>Details of change 2</data>
    </change-item>
    <change-item product="productA productB">
      <change-person>Richard Smith</change-person>
      <change-completed>2013-07-20</change-completed>
      <change-summary>Made change 3 to both products</change-summary>
      <data>Details of change 3</data>
    </change-item>
  </change-historylist>
<!--...-->
</prolog>