Rules for a good announcement

Writing for the digital medium (email, blog posts, slack, discord, etc.) requires breaking the rules you learned in school.

I’m going to explain some rules I use to create announcements for email and slack. These rules work for other digital mediums as well.

To be clear; By announcement I mean notices saying there will be an outage or an upgrade, etc.

I have seen a lot announcements that are overly verbose and hard to understand.

When announcements are too verbose, too hard to understand, or too complicated then people won’t read them.

Subject, What, When, Actions, Details

A good announcement consists of 5 main parts:

• An easy to read subject.
• A description of what the impact is.
• When this is happening.
• Any actions the user must take.
• Any extra details.

Each section should be short, clear and separate.

Except for the Action and Details, each item should never be more than 5-7 words long. This is about the most a human can scan at a glance.

This means paragraphs will be a single sentence most of the time.

Each line should start with most important words. The reader will decide to read a paragraph based on the first couple words. If they aren’t interesting, the reader will skip to the next line.

Subject

The subject should be short (1-4 words. A date or time may also be appropriate).

It should use terms that either people know instantly or can lookup readily.

Most people will see it when scanning email subjects in their client or scanning a Slack channel for something interesting.

Don’t use a lot of Emoji (e.g., 🚨), ALL BOLD, or lots of asterisks (*). We want to avoid going back to 90s web design practices.

What

This should be one sentence with about 5–7 words.

An example:

sanjose7a server maintenance

Leave out articles (the in the case above) and other extra words.

Try not to repeat yourself. Avoid “down for maintenance” when either “down” or “maintenance” will work.

When

The date and time, including the year and timezone.

Make sure you use both English and computer-style date and time (e.g. ISO 8601 and RFC3339 ).

Example:

Friday, April 13th at 4–6 p.m. Eastern Time
2018-04-13 16:00–18:00 EDT

Actions

You should state what the user should do in clear plain language.

A good approach is to use numbered lists with each step being one simple instruction.

Telling the user they have nothing to do is also acceptable.

Details

Describe what is going on. Use language you would use to explain the event to your a colleague.