Writing information messages

Changes, updates and deviations

Changes increase people’s information needs. Deviations and downtime require fast and continuous information; planned changes require it in advance, while general help and instructions must be ever aware of context. The following guidelines and examples help us make users as self-serviced as possible, considering their circumstances.

The alert message component can be relevant to look at as well.

Guidelines

Write long enough

Start without limitations; write what comes to mind. Then edit and rewrite. Good communication isn’t necessarily short but concise. Aim to end up with only the amount of words necessary.

Use action over causes

Lead with action. Start by telling people what’s happening, how issues affect them and what they can do next. If details are necessary, consider using a separate page or a disclosure.

Speak like a human to humans

Consider the recipients. Are they technical people or have otherwise sufficient domain knowledge? Use common words in plain sentences. Avoid abbreviations, jargon and a unique tone of voice; they don’t make us sound more competent, but the readers feel stupid.

Consider context

Know where the message ends up. Use words that match those in the interface. Are there other messages nearby? Can we omit the information the interface provides?

Deviation and downtime are opportunities

Keeping users in the loop provides a sense of progress during severe incidents; it shows that we can handle errors. Progress updates allow us to tell users about the problem before we have the complete picture ourselves. Timestamps and promised updates indicate progress. When the incident is over, it’s good information to show a resolve message.

Quick reference

Formula for service changes

1. What’s happening, and when.
2. How does it affect the customer?
3. What does the person have to do – or don’t they have to do anything? Is there anything that they might misunderstand or worry about?

Checklist

• The names are correct. “Pickup Point API”, not “PickuppointAPI”. “Mybring”, not “MyBring”.
• The message doesn’t start with “because of”.
• The link texts are descriptive and not things like “here”, “link”, “this” and “more”.
• We use complete service names (“Pakke i Postkassen” instead of “PiP”)
• We have proofread it.
• We have formatted dates, numbers and units according to format guidelines.
• We don’t include (unless strictly necessary) things like:
  • Detailed descriptions of cause; we are not writing an incident report or making a press release.
  • Apologies; users can’t do anything with them and don’t call support to get them.
  • “Please” and other pleasantries.

Examples

Service change

Unclear

We are always improving and customers are so important to us and we want to serve them in the best possible way. So during the summer we will introduce three new options for securing API integrations. There will be a period where you can run without, but it will be mandatory to use one of them from Sept. 4th. Read more.

Clearer

The API will require a new security check from 4 September. All integrations need the check in order to continue working. You can update existing integrations today by following the step-by-step guide to API security.

What, when and how, along with a descriptive link text. The first two paragraphs are almost identical but are a way to restate and clarify the importance.

Info in advance

Too detailed

It’s that time of the year again! Christmas is here and that means deliveries that usually take 2-4 business days and deliveries that take 3-5 business days might take 4-6 business days and 5-7 business days, depending on location and distance.

More concise

Between 12 December and 4 January deliveries can take up to two extra business days.

Holidays are rarely a surprise. Mentioning a self-evident cause isn’t necessarily wrong, but avoid using a particular tone of voice or holiday greeting language. We’re not giving the gift of service delay.

Deviation

Too little, too technical

The TUB Mainframe and FoamCore are experiencing some hiccups. Please try again later.

Less technical, more reassuring

We currently cannot handle your request because of a stability issue in one of our supporting systems. We are working on it. Try again later.

Longer isn’t necessarily bad. Using words the users know is always better. And systems don’t experience anything, certainly not hiccups – be careful with personifying.

Explanation

Over explaining

Because of rainy weather, the equipment needs to be transported back inside. If not, the aforementioned equipment will get hit by the rain, get wet and might not work as intended.

Action

We need to get the equipment inside because it’s raining.

What to do and a reason. No need to over-explain what is evident from context, and certainly not in backwards sentences.