The most important part of a Change Management process is simply being able to tell the stakeholders about an upcoming change. Especially in a world where email is often left unread, there is no one “centralized” group or team making changes, and instant messenger is possibly the only real means of communication. Ideally, a Master Station Log (MSL) or Service Status Page is a focal point for communications about planned events and emergent events. Additional policies may define channels used to broadcast those messages to get the attention of the target audience. Whether or not any of that exists, writing that change announcement really is the most critical part.

The following template uses two key techniques for making an effective announcement of a planned change. First, brevity. Bullet points help paired with complete sentences, but no real paragraphs. Rather, link to more detailed information. Secondly, specifically write the announcement so that if a user is not affected by this change they need not read past the first sentence or phrase. Knowing that folks are more and more likely to stop reading the further into the announcement they go, write for that.

Template

Subject

Only included when distributing by email that requires a subject line. This should be a shortened form of the answer to the “What?” question.

What?

A brief sentence or two describing what will change. This is the TL;DR summary.

The Dev/QA Grafana service found at https://foobar.example.com is being deprecated. The service is being migrated to https://grafana.qa.example.com.

When?

State the exact time the change will be effective. If there is a downtime window for the change that should be stated here as well. Be specific and state the timezone. Prefer the timezone of the users rather than UTC.

Monday, August 23rd, 2021 at 10:00 AM Eastern Time / 7:00 AM Pacific.

Why?

What benefit will the users receive from this change? Bullet points may help in this section.

• This Grafana instance is being integrated with the centralized observability services for the Dev/QA environment.
• Grafana will be upgraded to 7.5.10 to match the production environment.
• Dashboards in the new Grafana instance are stored in AWS RDS and backed up nightly.

What Do I Need To Do?

This section lists any actions that affected users may need to do. Again, a few short bullet points or a single sentence is the goal here. Complicated upgrade steps the user must perform is an anti-pattern.

• Update your bookmarks to use the new Grafana instance at https://grafana.qa.example.com.
• The new instance is already running and you may begin using it today.

What About My Dashboards?

Here is a great place to add one or two common questions that a user that has read this far may have. Use a new section/header for each question and make the actual question the text used for that header. Several common questions may be addressed this way, but using more than 3 is a sign of over complication. This section is optional.

Dashboards in the old Grafana are being migrated over to the new Dev/QA Grafana nightly. After Monday, August 23rd, this will cease and the old URL will redirect users to the new Grafana service.

Who Can Answer Questions?

This is the final section and is a reference for finding more information about the planned event or maintenance. Important things to list here is where to ask questions and where to file tickets. Also, if there is a ticket or wiki document describing more detail about this project that users might find helpful, that can be referenced here.

• Slack: #observability-team
• Jira Tickets can be opened in the OBSRV project.
• The Centralized Grafana project is ticket OBSRV-1234 (link) and documented in the wiki at (link).