Release Management

Use Cases

Please review use cases on release management, including descriptions from several product vendors, at

Basic change control requirements

medical device industry comments

from JHackos 21 January 2012

First comment At the simplest level, we have used metadata at the topic level to track topic status. Our file management architecture uses subject area folders with master maps for each subject area that include all topics in that SA. I created a fairly simple plug-in to the toolkit that generates an XML file for each subject area map, which I then pull into an Excel dashboard. Each SA has a tab that tracks topic creator and status, and percentages are rolled up to a quick look dashboard view for all SAs. We used this a lot during our daily scrums when we were heavy into the writing cycle of our most recent project.

When we got into the review cycle, we had to find ways to account for specific process artifacts that needed to be traced back to individual topics, such as System Change Requests (SCRs) and content that satisfied hazard mitigation requirements from Safety/Reliability. SCRs may come from software development or technical services, and are basically a request to change content that are entered into software development's SCR system. Hazard mitigation occurs when Safety/Reliability identifies hazard conditions that will be mitigated by content in the documentation, which they then need to trace to the specific content.

In each of those cases we need to trace back to a specific topic in our information set and tie it to a specific change driver, whether that's an SCR number or a record in the hazard mitigation process. We include an ID number (SCR number or HM number) in our topic metadata (<prolog>) using the <data> element with a specific name/value pair. We have to report on those traceability items back to different groups, so I've created some reporting plug-ins to support that. There are some variations depending on what each group wants, but basically the reports list the topic, its location in our system, and the issue number. We also include similar information using the <draft-comment> element so we can provide those groups with the topic content specifically pointing out the change location in the content itself. We also include the changeset number from Visual Studio when we report back to these groups, which includes when it was checked in and by whom, but that's outside DITA.

Second comment

I'd characterize our metadata as varying according to the object type: e.g. module, illustration, screen snap, topic, book (information build list). Any change is auto-tracked for who made the change (requires secure and unique user IDs) and when the change was made (recorded to the second). Additionally, we always require a free-form field be filled in, to capture what change was made and why (with more information captured being better than less). Then, for each unique object type, there are some metadata fields that are autopopulated, and others that require user input (e.g. from drop-down lists, checklists, radio buttons, free-form text).

The details are extensive and unique to our requirements (e.g. business unit, deliverable type, "cloned from"). The metadata fields also change over time, as new business and technical requirements emerge.

Medical Device Industry summary

Focus on the topic


We recognize that significant documentation will be required, most likely in the Arch spec.

Must emphasize:

Lang spec

What the elements are and the rules.

Arch spec

"Roll up" of changehistory domain elements to an interim format (which may also be the changehistory domain.

White paper

"Maturity model" concept, where SubjectScheme-driven is most mature. Using SubjectScheme to implement the Foo History feature in DITA.

Using a script to aggregate topic-based changehistory.

Writing changehistory domain content to the Topic output (below/above content).

Writing all changes in a single book-wide topic with the changehistory domain (as opposed to a table, or whatever)


Draft proposal (per 1.3 template)



Usage notes

Short description

Allow authors to record topic change notices without need for external agents or documents. These change notices can then be aggregated and presented to end users at the time of document release.


Longer description

The Tech Comm SC proposes that a domain be introduced for DITA 1.3 that enables content workers to track changes at the topic level when changes are made. This domain satisfies (or provides the underpinnings to satisfy) these requirements:
• Must be able capture change information in topics. Even in the case of a robust CMS solution, it is necessary to provide a semantic structure for stowing this information during content exchanges (mergers, acquisitions, licensing, rebranding, CMS migration, etc.)
• Method must be described in the DITA spec to provide a standard way of exchanging this information in a controlled way, even if the originating environment uses some other method.
• Change information must be subject to the same applicability methods that affect other content. That is, change information must include @props attributes, which presupposes the use of elements in the DITA namespace.
• Change information may be aggregated during a preprocess or independent process to compile a revision history report based on information supplied in the change history, including—but not limited to date/time. Many useful internal status reports come to mind.\

The model for this domain comes from bookmap’s “bookchangehistory”, with modifications.

The scope of this proposal is limited to:
• The domain design requirements
• Processing examples
• If necessary, usage notes regarding processing order with respect to link resolution, flagging/filtering, and keyspace construction.

{Include links to previous discussion, other existing background.}

Statement of Requirement

Authors must be able to record, for inclusion in release documents, notices of changes to topic content, including such details as change author, change date, motivation (e.g., SME, standards body), change location, and change summary. In addition, for some users, the history of the change must be traceable as well—date started, date completed, date approved. These notices must be subject to ditaval filtering.

{Describe the requirements that this proposal is intended to satisfy, stated in implementation-neutral terms. These requirements should then be reflected in the use cases. For example, "Authors must be able to identify mentions of foo-type objects in order to enable both typographic distinction and automatic indexing of specific foo instances". }

Use Cases

For organizations that produce successive revisions of long documents, when revisions subsequent to the first are published, customers would like to have substantive changes brought to their attention without having to review the entire document. Automatic processes, such as difference documents, may result in huge lists of ‘changes’ that are simply cosmetic. This proposal offers a framework that would allow such an organization to have its authors record—in effect to pre-record—a notice of a change at the time change is made. At release time, these notices are gathered up and included in the document release. This feature provides only the framework for recording change notices; no specific application or appearance is required. Any collection and exposure of the change notices recorded could be done outside the scope of document generation. Those not using the feature would incur no penalty.

{Describe this feature's use, as if ideally implemented. Include any presentation expectations, if appropriate.}


simple to medium: The DTD changes are easy—but not trivial—to implement.

{Major (design work needs to be done) or Trivial (clear what to suggest; could be done in less than a day). Expand on understood Major exposures.}

Technical requirements

DTD changes: Add new elements to the DITA topic prolog element. Processing: No changes to processing are required. If utilized, the information in the new elements can be gathered up at publication time, using an Xquery, for example, and published separately or included in the document as an annex. editor support: Any editor that didn’t currently support changes to the prolog element would need to be updated to allow such access.

{That is, DTD changes, processing impact, additional setup by users, etc..}

New or changed spec language

We propose to base the additions on the bookchangehistory element of bookmap; thus, some of the language needed to describe the changes is already in the spec. Any changes to the bookchangehistory elements would need to be documented in full.

{Provide either new language for the DITA architecture or DITA language reference specifications or provide editing instructions for amending existing language.}


TCSC: design/approval, implementation. TC: review/approval process. DITA OT: We are not recommending any action by the DITA OT designers. Third parties: Editor/CMS changes, workflow tie-ins, editor stylesheets. Since these are new elements (and optional ones) there is no conversion cost. (No existing content is affected.) The DITA topic becomes slightly more complex.

{What is the time and effort required for the TC and for implementors, both the maintainers of the normative constraint specifications (DTDs, schemas, etc.), for the DITA Open Toolkit, and for third-party tools such as editors, content management systems, etc.}


Those who must provide customers with document release information will be able to provide this without using external documents.It is expected that a significant portion of those using DITA would find such a facility useful or even desirable. These users would find a significant benefit in keeping the change notice recordsa together with the actual content.

{What is the benefit we expect to get? How many people would probably make use of it? (everybody/many/few) How much of a positive impact would that make for those users? (significant/minor)}

Stage 2 proposal: markup suggestions

This section details the proposed markup modifications. 1) create a new "changehistory" domain that can be integrated by map and topic shells 2) re-factor bookmap.mod to specify some elements in a separate domain (so this can be used by bookmap). 3) specify required and optional processing expectations

bookchangehistory as a model

The following image shows a graphical view of the bookchangehistory structure; note that "Group1" is defined in a subsequent graphic:

WHERE "Group1" has the same reused structure previously illustrated.

The content model is much more loose than is required for the changehistory proposal. A simple, more rigid structure (show below) will clarify the intent of the semantics. Essentially, for each notable change event (edit, review, etc.), agents may record information that identifies the person, purpose, and description of the change. Keeping each change event within a separate "change-item" container allows appliances to selectively ignore certain change events based on time or other considerations. Below is a graphical view of the proposed changehistory proposal.

WHERE "Group1" has the same reused structure previously illustrated.

What is not specified in the proposed model:

Cleanup required

Release Change History

Discussion on use of book-level change history to track changes at the topic level:

Note (seth park Jan 23 2012): I implemented this "change domain" for Freescale. The processing plan is to use the date information (in addition to traditional applicability attribution) to determine whether a specific change item is pulled into a publication-wide revision history. Processing has not yet been implemented, pending technical/business issues:

ReleaseManagementWiki (last edited 2013-03-31 23:18:36 by joann.hackos)