Release management domain

Darwin Information Typing Architecture (DITA) Version 1.3 Part 2: Technical Content Edition

version
1.3
author
OASIS DITA Technical Committee

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.

Figure. 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.

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

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. 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>