# DITA Best Practices : Release Notes and Change Log Structure

Created by Kelly Mankenberg, last modified on Jan 11, 2017

The Release Notes artifact is designed to function using both a Release Notes page and associated Change Log page.

Note

While this example uses the more complex structure of the Expere Authoring Tools Release Notes, you may find that your own Release Notes structure to be easier to maintain. And while this is the recommended standard for Release Notes artifacts published by InfoDev, you may find your own documents to be somewhat simpler.

# Main Structure

The screen capture below highlights the structure.

- The Release Notes link in the navigation displays the Release Notes topic. This page contains the links to the release note items new for the latest release.
- The Change Log pages contain the actual individual release notes in an ongoing manner (release notes are never removed).

# Change Log Topics

Change Log topics contain the actual release notes for individual defects and enhancements being reported.

Each Change Log topic follows the same structure, as outlined here.

- Concept
  - Prolog
  - Conbody
    - Section (revision heading)
    - Section (Enhancements heading)
      - simpletable (release note)
      - simpletable (release note)
      - etc
    - Section (Defects heading)
      - simpletable (release note)
      - simpletable (release note)
      - Etc
    - Section (revision heading)
    - Section (Enhancements heading)
      - simpletable (release note)
      - simpletable (release note)
      - etc
    - Section (Defects heading)
      - simpletable (release note)
      - simpletable (release note)
      - Etc

## Revision Heading Section

### Structure

The Revision Heading section is structured as follows:

    <section><P><ph>Revision XXXX.X</ph>  (release Dates)<p></section>

- Top Rule: The outputclass attribute of <section> must have a value of toprulemedium. This provides a visual separation between revisions.
- Blue Button: The <ph> containing the revision level must have an outputclass of btn_revision. This provides a blue button around the revision level and provides space between the button and the revision dates.

# Release Notes Topic

Release notes can easily be inserted into a Change Log file by using the oXygen Action detailed in Creating an oXygen Action. This is simply a snippet of code that can be inserted automatically any place that a simpletable is valid.

## Release Note Code

<simpletable frame="none" relcolwidth="1.0*">

<sthead>

<stentry outputclass="rntitle">TITLE</stentry>

</sthead>

<strow>

<stentry>

<ul>

<li>

<b>Type:</b> Defect/Enhancement</li>

<li>

<b>Reference:</b> PBINumber</li>

<li>

<b>Compliance Impacts:</b> This item is/is not a compliance or regulatory issue.</li>

<li>

<b>Documentation Impacts:</b> No documentation impact</li>

</ul>

</stentry>

</strow>

<strow>

<stentry>

<b> Issue/Summary:</b>

</stentry>

</strow>

<strow>

<stentry>

<b> Solution/Technical Notes:

</stentry>

</strow>

<strow>

<stentry>

<b> Implementation Notes: This feature requires a Requirements and Content Editor Tool / Expere Engine / Content Style Sheets / Expere Server Tools (choose one: Expere Administration Tool/Customer Facing Outlines/Build Doc Previews/Data Dictionary Builder) update.</stentry>

</strow>

</simpletable>

## Release Note Completion

After the simpletable has been inserted, the following items must be completed:

- Title: Replace TITLE with the actual title of the release note
- Type: Delete the non-matching item (e.g. if the PBI is a defect, delete \Enhancement)
- Reference: replace PBINumber with the actual PBI number.
- Compliance Impacts: If there are any impacts, delete /is not. Otherwise delete is/.
- Documentation Impacts: If there are no documentation (user guide) impacts, leave this unchanged. If the PBI does require user guide modification, insert the name of the affected user guide and hyperlink it to the URL of the user guide.
- Issue/Summary: If the PBI is a Defect, delete /Summary and complete the issue information. Otherwise, if the PBI is an enhancement, delete /Issue and complete the summary information.
- Solution/Technical Notes: If the PBI is a Defect, delete /Technical Notes and complete the information. Otherwise, if the PBI is an enhancement, delete /Solution and complete the information.
- Implementation Notes: Delete all text that does not apply. For example, if the PBI is an RE3 change, delete all but Requirements and Content Editor Tool. If the PBI is regarding an Expere Server Tools change, then delete all but the appropriate choice in parenthesis.

## Attachments:

image2017-1-11_16-21-47.png (image/png)
image2017-1-11_16-24-18.png (image/png)
image2017-1-11_16-26-37.png (image/png)