Govern, Version, and Batch Changes to Application Documentation Templates

This chapter explains how to manage changes to the Application Documentation Template, so that templates can improve without causing constant disruption, and so that every Application’s documentation catches up with each change.

Why Template Changes Need Governance

The template must evolve: stakeholders’ needs change, new regulations appear, and experience reveals gaps. But every template change can make the documentation of every existing Application incomplete. Without governance, frequent and unannounced changes leave Application teams chasing a moving target, and rarely changed Applications fall further and further behind.

Establish Template Change Governance

Govern template changes as follows:

• Version every template and give it an effective date. Each version of the template carries a version number and the date from which it applies. Each Application’s documentation records which template version it conforms to.

• Batch changes on a predictable schedule. The template owner gathers changes and publishes them together on a predictable schedule, with advance notice to stakeholders and Application teams. Off-cycle changes are reserved for urgent needs, such as a new regulatory requirement.

• Notify Application Managers and critical stakeholders. When a new template version is published, every Application Manager and critical stakeholder is told what changed and what each Application must update.

• Schedule the updates immediately. When a template changes, Application Managers and their teams should immediately add the required documentation updates to the Application’s backlog and complete them as soon as possible.

• Enforce a Release gate as the minimum. At a minimum, an Application’s next Release may not be deployed to Production until its documentation conforms to the current template version.

• Apply a time-based backstop. Some Applications, particularly older ones, are rarely released. To ensure that they also catch up, require conformance within a set period after the template’s effective date. If that period passes without conformance, record a Knowledge Debt Item and an entry in the Enterprise Risk Register.

Conformance to the current template is tracked and reported across all Applications, as described in the chapter “Track Application Documentation Conformance with Red-Amber-Green (RAG) Reporting.”

Document and Share Template Versions and Changes

Publish, in the Digital Library alongside the template itself, each template version, its effective date, and a summary of what changed, so that Application teams can see exactly what they must update.

Best Practice: Version, Batch, and Announce Template Changes, and Schedule Updates Immediately

It is a best practice to both establish and document the solution for template change: version templates with effective dates, batch changes on a predictable schedule with advance notice, require Application teams to schedule the resulting updates immediately, and back that up with both a Release gate and a time-based deadline.

Benefits: Predictable, versioned changes let Application teams plan documentation work instead of reacting to surprises, while immediate scheduling, the Release gate, and the time-based backstop together ensure that every Application, including rarely changed ones, eventually reflects what the enterprise has learned.

Common Antipatterns

Connections to Related IF4IT Practices and Inventories

The Release Management Best Practices describes the Releases at which template conformance is checked. The Technical Debt Management Best Practices addresses the related practice of tracking and scheduling the remediation of accumulated shortfalls.