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, and general help and instructions must be ever aware of context. The following guidelines expands upon Writing for Mybring users with examples to help users to be as self-serviced as possible.

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

Guidelines

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

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

Consider context

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

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 can indicate progress. When the incident is over, it’s good information to show a resolve message.

Formula for changes to APIs, interfaces or services

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” or Pickup Point Application. “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 full 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 Cloud 3000 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.