Taming the Wild West of Release Notes with Markdown DITA

The release note creation and curation process typically involves chaos, hassle, confusion, and last-minute changes for both the Product Managers who write and review the release notes and (especially!) the technical writer in charge of handling, cleaning up, and publishing the release notes. In one case, the process involved a single, giant Word file that only one Product Manager could access at a time and a mess of Word drafts in which different Product Managers reviewed different snapshots of the release notes (each of which may or may not have included all the latest feedback from other Product Managers!).

As is to be expected for release notes, there are  always last-minute changes, but…

You too can conquer the release notes chaos with Markdown DITA and transform the Wild West of release notes into a controlled process in which…

1. Product Managers create release note topics using a customized (free!) Markdown DITA authoring tool.

2. Product Managers submit their content to a dedicated staging folder in the source control system.

3. The technical writer unifies the voice/style of the writing and cleans up the release note content, transforming this content to XML DITA in the source control system.

4. Continuous Integration builds ensure that the latest version of the release note content is always available.

5. The technical writer generates Word review drafts of the latest release notes so that the Product Managers can review and provide feedback using the mechanism with which they are most comfortable.

6. A round-tripping script converts the cleaned-up release note content from XML DITA back to Markdown DITA in the source control system so that the Product Managers can make additional changes to this content as needed.

What can the audience expect to learn?

Creating release notes is usually a hassle, especially with one technical writer trying to corral the disparate content of a bunch of contributing (non-technical-writer!) Product Managers. This presentation explains one way to use Markdown DITA to improve the efficiency and ease of this process.

Meet the presenter

Debbie Femia
Content Strategy Director


⇐Return to Agenda