A well run service needs routine maintenance. Without regular system maintenance, updates would go uninstalled, bugs would go unsquashed, patches would go … unpatched.

It’s important for the long-term reliability of your service that ops teams and system administrators feel confident and empowered about announcing maintenance activities.

Whether you’re running a public service on the web or an internal service for your team, announcing downtime is never easy. Unfortunately, many teams don’t take the right approach. Offering the briefest update possible and hoping nobody notices – what you could call the slide-under-the-radar method – actually sets you up for failure.

The goal of a planned maintenance announcement should be to get the right people informed and confident about the upcoming maintenance.

Here’s our guide to announcing scheduled maintenance, along with some examples from our friends who are doing it well.

Before everything, understand the impact

Understanding the impact the maintenance will have on end users is critical to a successful maintenance announcement. Before anything else, you should be able to clearly answer all of these questions. This will give you a scope of impact, which will guide your entire strategy.

  • How high of a priority is the service to your users? (If you’re unsure of how to answer, ask how detrimental the outage would be for folks’ ability to get work done. Can they easily work without it?)
  • Will this take entire services offline?
  • If not, will there be degraded performance or functionality to affected services?
  • Will you be able to host the maintenance period during non-peak hours for all users? (This is tricky with users across different time zones.)
  • How many users will be effected? All? A small percentage?
  • What’s the expected length of the maintenance period?
  • Do you have an action that you are asking your users to take?
  • What’s the perceived risk of problems arising that could prolong the downtime period, or affect other services?

Some of these questions will be tricky to answer. Do your best to make the most educated estimates you can. The point of the exercise is to get you thinking about the interruption from the user’s perspective. There isn’t a secret formula, but once you’ve reflected on these questions you’ll have a much sharper picture of the scope and impact of your maintenance period.

In general, big impact maintenance on big services calls for a more robust announcements schedule: more updates, more channels, and longer lead time. The lower you are on the critical impact side of these questions, the less detailed and frequent your updates need to be.

In general, we lobby for over-communicating service issues. But it’s easy to become the boy who cried wolf with maintenance announcements. If you blow up your users’ inboxes every week with multiple announcements for every tiny update, your audience is going to start ignoring you. That means they might ignore an update that’s really critical. Be judicious. First understand the impact and let that guide you.

Give enough lead time, give the right amount of reminders

Larger impacts call for longer lead time and more frequent updates before the maintenance. For small updates with no expected impact on users, one announcement message is usually enough. As the impact goes up, consider adding a reminder update right before the maintenance. In Statuspage, for example, we include an option to send a reminder message an hour before the maintenance period begins.

image or a reminder message for a maintenance window

You don’t want updates so far in advance that users forget about them. In general, anything longer than a week of advance notice will need a reminder closer to the actual downtime. The further in advance your initial announcement, the more reminder updates you should schedule in. Consider multiple reminders and longer lead times for cases when users’ critical workflow will be interrupted and cases where you need them to take some action (like change a password or install new software).

Know your audience and your channels

Email is the most common channel for announcing scheduled maintenance. Social media messages and in-app banners are also popular.

We certainly recommend using a status page to announce maintenance periods. The benefit is that it creates a single place to manage and post your scheduled maintenance updates. You can post announcements to your page and have email announcements sent to subscribers automatically.

Social media posts are helpful, too, but don’t assume all your users will see those updates. This is best used as a supplement to an email and Statuspage strategy. Embedding an announcement in the app that will be impacted is another approach, and a great way to put the update in context. This is best done when you also link out to a Statuspage with more details, otherwise you’ll be taking up too much space on the user’s screen.

example of a status update from the twitter feed of Heroku

Here’s a great example of Heroku announcing status to Twitter followers. Notice they have a dedicated Twitter account specifically for status updates and link out to their status page. Heroku also has a great page which explains their approach to maintenance periods: Platform Updates, Maintenance and Notifications.

Include the right details, but not too much

It’s easy to drown your readers in minutiae with a maintenance update. Consider what details they’ll need to know and the most common sense way to explain them. You don’t want to talk down to anyone, so use your product and user base to gauge how technical your message should be.

This announcement from DigitalOcean tells the customer exactly what they need to know with the right level of specificity.

Notice how they include:

  • What team is doing the work
  • Exactly what work is being done
  • What services will and will not be impacted
  • How to follow up with questions or concerns
  • Specifically when the maintenance window is scheduled for (broken out from other text so it’s easy to find and read)
  • The name of the sender

The overall effect is a great maintenance announcement. Notice it looks less like a boilerplate announcement and more like a helpful letter from a real person.

Also notice how helpful it is to break out the time windows from the other text. Be mindful that a lot of your readers will immediately recognize a maintenance announcement when they see one, and they’ll want to skim directly to the time window. Make this easy for them to find.

A note on how to set time zones

Setting time windows is an important part of scheduling maintenance. Notice DigitalOcean and Heroku both display the times in a neutral time zone. It’s a nice touch to add a parenthetical translation for a common time zone (like Heroku does). Also, military time is the generally accepted approach here and was designed to avoid confusion in situations just like this.

Write like a human

Many maintenance announcements are written in a robotic, bland tone, perhaps with the thinking that it makes the message sound more important or official. More likely it leads to these updates being ignored. Remember that there are real people reading your messages. Write in a helpful tone, like you would talk to a colleague in a normal workplace setting.

Take a look at this excellent example from ToutApp (via goodemailcopy.com)

example of a detailed maintenance message from tout app

The ToutApp update is less technical than DigitalOcean’s but still incredibly detailed and helplful. This note covers all the bases for what a good maintenance update should deliver, and also sprinkles in a human touch. The team here does a great job making it clear exactly why they’re taking the services offline and what’s in it for the user: added capacity, faster service, and better uptime. Setting up the “why” like this and talking to the audience like real people has a great effect of turning what might be a bad situation into a memorable experience.

Closing tips

Follow the Golden Rule when it comes to maintenance announcements. Treat your users the way you’d like to be treated. Before making things too complicated, be sure you’re seeing things from the user’s perspective.

Even if you ignore all the other advice and totally wing it, follow these three guidelines and you’ll be off to a good start:

  1. Understand the impact on users
  2. Tailor your announcement strategy to match that impact
  3. Be clear and helpful

Here are a few other helpful resources:

Scheduled maintenance message examples and inspiration