
Our language framework helps guide all of our writing for our digital platforms. The language and words we use have a deep impact on the user experience and our business outcomes.

Our goals for this framework are to:

- **Create consistency** across our platforms to make our experience usable, predictable, and delightful.
- **Empower our team** and make it easy for anyone working on our digital platforms to write clear, effective, and useful content.


## Writing for Pistachio

The Pistachio design system introduces an extra level of complexity in copywriting for our digital platforms.

Here are a few key mindsets for writing for our digital platforms:

- **Write for Pistachio first.** Treat it like a “base layer” that you’ll build on to capture and convey a distinct personality for each of our brands.
- **Use the same words to describe nouns and verbs.** By using the same words, we’ll create a consistent and usable experience for all of our brands.
- **Use voice and tone to reflect each brand’s personality.** For more, see the Voice & Tone section.

Goals & principles


One of the ways we create a consistent and familiar experience for our users is by speaking with a consistent voice throughout our product and content while being aware of our tone.

## What’s the difference between voice and tone?

One of the ways we create a consistent and familiar experience for our users is by speaking with a consistent voice throughout our product and content while being aware of our tone.

What’s the difference between voice and tone? Think of it this way: our **voice** is a personification of who we are. We always have the same voice. But, our **tone** changes to match our context and situation.

For example, when our customers are cooking their first meal, they might be feeling excited, successful, and maybe a bit nervous. We can cheer them on and congratulate them when they’re finished cooking.

But when our customers experience something going wrong, such as an ingredient missing from their box, they’re probably feeling annoyed and a bit stressed out. We can recognize what went wrong, apologize, and tell them what will happen next.

## Voice guidelines

Each of our brands has a distinct voice and character. But since we use Pistachio, the foundation for all of our digital platforms, we have a **shared voice** that’s the basis of our writing for all of our digital platforms. We write first in this voice and then build off of it to infuse each brand’s unique personality.

When we write in our shared voice, we are always:

``TODO: This section is in an early draft form.``

### Optimistic

- Give people energy through our own positivity
- Help our customers succeed and don’t talk down to them
- Assume positive intent, even when things go wrong

### Conversational

- Be plain-spoken
- Use our user’s language
   
### Authentic

- Communicate clearly and honestly, even when we make a mistake
- Be direct but compassionate
- Let our love for cooking and food shine through

When we build off of our shared voice for **Marley Spoon**, we are also:

### Confident

- Speak with confidence
- Be specific when explaining
    
### Interested

- Be empathetic
    
### Interesting

- Connect our love for food to the richness of life

When we build off of our shared voice for **Dinnerly**, we are also:

### Quirky

- Our sense of humour doesn’t take itself too seriously. We’re obviously punny and straight-faced, but never sarcastic or cynical.
    
### Playful

- ``TODO``
    
### Down to earth

- Connect our love for food to the richness of life
    
## Using tone of voice

Our tone is more than just the words we choose: it’s the way that we choose to share our personality through our voice.

We can express any given message in wildly different ways. To find the right tone for any given message, consider the four dimensions of tone of voice:

1. Funny vs. serious.
2. Formal vs. casual.
3. Respectful vs. irreverent.
4. Enthusiastic vs. matter-of-fact.

Vary these dimensions to meet the user’s emotional and situational context at a given moment in time.

### Positive situations

```usage
<Usage type="yes">
### Yes
- Be encouraging
- Express authentic pride
</Usage>
<Usage type="no">
### No
- Don’t take credit for their success
- Don’t assume it was easy
</Usage>
```

### Neutral situations

```usage
<Usage type="yes">
### Yes
- Express confidence and connect value
</Usage>
<Usage type="no">
### No
- Don’t create uncertainty or tell people “what to do”
</Usage>
```

### Negative situations

```usage
<Usage type="yes">
### Yes
- Be honest and direct about problems and provide next steps
- Use conversational but straightforward language
</Usage>
<Usage type="no">
### No
- Don’t minimize the problem
- Don’t use negative or technical words
</Usage>
```

When we write for our distinct brand voices, each brand has its own “range” along these dimensions of tone of voice. For example, Dinnerly can take a more enthusiastic tone of voice than Marley Spoon for a message for the same positive situation.

Voice & tone


The content in our digital products and messages shape how our users perceive and use our platforms to get things done. Our writing must help our users understand and take action.

## Heading and subheadings

Headings and subheadings in our interfaces have three goals:

- Help users identify their place
- Help users understand how things are organized
- Help users predict what actions they can take

Some specific guidelines for writing headings and subheadings:

- **Be concise.** Headings and subheadings should be scannable and use only as many words are needed to convey their meaning.
- **Write in sentence case.** Sentence case makes it feel less stiff and formal.
- **Don’t use punctuation** like periods or semicolons.

```usage
<Usage type="yes">
### Yes
- `TO DO`
</Usage>
<Usage type="no">
### No
- `TO DO`
</Usage>
```

### Conversational headings
When we’re talking, we connect words with articles like “the,” “for,” “these,” and “an.” If we remove these from our writing, it makes our copy feel stiff and complicated. For conversational headings, use articles and write full sentences.

```usage
<Usage type="yes">
### Yes
- `TO DO`
</Usage>
<Usage type="no">
### No
- `TO DO`
</Usage>
```

### Microcopy
For labels and microcopy, prioritize short and actionable content by removing articles like “the” and “an.”

```usage
<Usage type="yes">
### Yes
- Add recipe
</Usage>
<Usage type="no">
### No
- Add this recipe
</Usage>
```

## Sentences
Sentences should provide real value and next steps for our users. They help users cycle between “What’s going on?” and “What do I do next?”

Some specific guidelines for writing sentences:

### Put action before outcome

Start sentences with strong verbs that help users understand what they will do. Include what the outcome of the action will be.

```usage
<Usage type="yes">
### Yes
- Add a recipe to your box.
</Usage>
<Usage type="no">
### No
- Recipes appear in your box after you add them.
</Usage>
```

### Use verbs instead of verb-noun phrases

Look for combinations of verbs and nouns that can be replaced by a single verb.

```usage
<Usage type="yes">
### Yes
- We will **refund** your order.
</Usage>
<Usage type="no">
### No
- We will **provide a refund** for your order.
</Usage>
```

### Don’t use permissive language

Give users confidence about what they should do.

```usage
<Usage type="yes">
### Yes
- Update your taste profile and get the recipes you’ll love most.
</Usage>
<Usage type="no">
### No
- Update your taste profile and you can get the recipes you’ll love most.
</Usage>
```

## Buttons
Buttons are one of the most important elements in our digital platforms. Most conversion actions are the direct result of the user clicking a button, and the labels used in buttons are at the point when a decision becomes an action.

Always write button labels in sentence case.

```usage
<Usage type="yes">
### Yes
- Skip this box
</Usage>
<Usage type="no">
### No
- Skip This Box
</Usage>
```

### Buttons for action

When buttons enable user actions, the formula is `verb` + `noun`.

```usage
<Usage type="yes">
### Yes
- Add recipe
- Explore fruit box
</Usage>
<Usage type="no">
### No
- Add
- Manage delivery
</Usage>
```

### Buttons in confirmations

When buttons are used as calls to action in confirmations, the formula `verb` + `noun` doesn’t have to be followed. Instead, use a verb to clearly convey outcomes, by connecting action to outcome.

```usage
<Usage type="yes">
### Yes
- Dicard changes? **Cancel / Discard**
</Usage>
<Usage type="no">
### No
- Discard changes? **No / Yes**
</Usage>
```

### Buttons for conversion
When buttons support conversion goals, the formula is `value` + `relevance`.

Instead of writing about what the user does (the action), write about what the user gets (the value). Then, make it more immediately relevant to the specific conversion context.

The length of a button label isn’t usually a problem, as long as they capture the relevant value for the user.

```usage
<Usage type="yes">
### Yes
- Send a friend a free box
- Get fresh fruit in your next box
</Usage>
<Usage type="no">
### No
- Send referral
- Add fruit box to your next box
</Usage>
```

Further reading:

- [How to write a call to action that converts](https://unbounce.com/conversion-rate-optimization/how-to-write-a-call-to-action-that-converts-with-case-sudies)

## Links

Links should provide information about what to expect about the associated actions or destination. Users should be able to predict what will happen as a result of clicking a link.

```usage
<Usage type="yes">
### Yes
- View [nutrition information](#).
</Usage>
<Usage type="no">
### No
- Want nutrition information? [Click here](#).</a>
</Usage>
```

### In sentences

Links in full sentences shouldn’t link the whole sentence, but instead only the text that describes the outcome of clicking the link.

```usage
<Usage type="yes">
### Yes
- Set up your [taste profile](#).
</Usage>
<Usage type="no">
### No
- [Set up your taste profile](#).
</Usage>
```

### Outside of sentences

Links that aren’t in full sentences should be treated similarly to buttons, and use the `verb` + `noun` pattern. Don’t punctuate, except with questions marks.

```usage
<Usage type="yes">
### Yes
- [Remove from box](#)
- [Don’t have an account?](#)
</Usage>
<Usage type="no">
### No
- [Remove from box.](#).
- [Don’t have an account](#)
</Usage>
```

## Error messages

Error messages have three goals:

- Explain simply and clearly that there is a problem and what that problem is.
- Provide a solution so that users can return and complete the process immediately.
- Turn the delay into an experience that is as pleasant as possible.

Some specific things to keep in mind when writing error messages:

### Write without rigidity

Keep it conversational. Adjusting the [tone of voice] to be more formal rather than casual is appropriate, but use restraint.

```usage
<Usage type="yes">
### Yes
- Postal code should have 6 digits
</Usage>
<Usage type="no">
### No
- Postal code is invalid
</Usage>
```

### Write without using the words error or failure

Again, keep it conversational. We’d never say “error!” in conversation if we didn’t understand something.

```usage
<Usage type="yes">
### Yes
- Sorry, we couldn’t save your changes. Try again?
</Usage>
<Usage type="no">
### No
- Failed to save changes.
</Usage>
```

## Confirmation messages

Confirmation messages and dialogues are shown when users take an action that can’t be undone, or is difficult to undo.

Confirmation **messages** should:

- Give the users a chance to confirm or cancel their action
- Be shown in response to a single action
- Always include one or two calls to action

Confirmation message **titles** should:

- Ask if they want to continue, using a `verb` + `noun` question.
- Write in sentence case. Sentence case makes it feel less stiff and formal.
- Don’t use punctuation like periods or semicolons, other than a question mark.

```usage
<Usage type="yes">
### Yes
- Discard unsaved changes?
</Usage>
<Usage type="no">
### No
- Discard?
</Usage>
```

Confirmation message **body content** should:

- Use plain language to explain action is irreversible or difficult to undo.

```usage
<Usage type="yes">
### Yes
- This can’t be undone
</Usage>
<Usage type="no">
### No
- If you discard changes, your box will remain unchanged.
</Usage>
```

Confirmation message **calls to action** should:

- Clearly convey outcomes, by connection action to outcome.

```usage
<Usage type="yes">
### Yes
- Discard changes? **Cancel** / **Discard**
</Usage>
<Usage type="no">
### No
- Discard changes? **No** / **Yes**
</Usage>
```
    
Special case: in the context of canceling accounts, use “Never mind” instead of “cancel” to prevent confusion.

```usage
<Usage type="yes">
### Yes
- Never mind / Cancel account
</Usage>
<Usage type="no">
### No
- Cancel / Cancel account
</Usage>
```

## Success messages

Success messages are shown to users in response to an action they performed, when it succeeds.

Success messages have three goals:

- Provide certainty to the users that the action was completed, and that everything is okay.
- Provide next steps for users, whether optional or mandatory.
- Provide positivity. When things go well, we can magnify the positive feeling and create affinity for our experience.

Some specific things to keep in mind when writing success messages:

### Talk about or to the user, not about the action

While it’s important to provide certainty that what the user wanted to do actually happened, it doesn’t need to be in the template “X successfully completed.” Sometimes, this certainty can even be implicit.

Imagine if we let people take and save a photo of a finished meal. When the photo is saved, we need to show a success message so they can be confident the photo was saved.

```usage
<Usage type="yes">
### Yes
- Looks amazing! Bon appetite!
</Usage>
<Usage type="no">
### No
- Photo successfully saved.
</Usage>
```

### If possible, provide a deeper and meaningful aspect of the action taken

Use success messages to reinforce the value that our users get from taking a given action.

If a user adds a fruit box to their weekly box, treat the success message as an opportunity to reinforce that choice.

```usage
<Usage type="yes">
### Yes
- Perfect! Your box will be bursting with fresh fruits every week!
</Usage>
<Usage type="no">
### No
- Fruit box added to your box.
</Usage>
```

## Empty states

Empty states are everywhere. They appear when there’s nothing to show. Sometimes, they appear when the user has yet to add something to a set of items. Other times, they appear when they try to find something and can’t.

Empty states are an opportunity to tell our users what there **is**, even when there’s nothing (``TODO quoting microcopy book``). 

An empty state is a chance to educate users about what’s supposed to be there, what can be done there, and how it will provide value to the user.

Some specific guidelines to keep in mind when writing content for empty states:

### Remember, empty states aren’t a bad thing

Avoid using negative words or phrases. Empty states are transitional and reveal potential.

```usage
<Usage type="yes">
### Yes
- `TODO`
</Usage>
<Usage type="no">
### No
- `TODO`
</Usage>
```

### Say what’s supposed to be here, or what can be done here

Use messages to describe what the user can see or do here, and how it will help them.

```usage
<Usage type="yes">
### Yes
- `TODO`
</Usage>
<Usage type="no">
### No
- `TODO`
</Usage>
```

### Provide a next step

If relevant, tell users exactly how to start using a feature and provide an action they can take.

```usage
<Usage type="yes">
### Yes
- `TODO`
</Usage>
<Usage type="no">
### No
- `TODO`
</Usage>
```

## Placeholders

Placeholders appear in form inputs before the user enters text. As a general rule of thumb, placeholders should be avoided except in very specific situations covered below.

```usage
<Usage type="yes">
### Use placeholders for:
- Fields we really want users to complete.
- Fields that users might not understand.
</Usage>
<Usage type="no">
### Don’t use placeholders as:
- Labels for form input fields.
- Formatting guidelines.
</Usage>
```

We use a few different approaches to placeholders.

### Questions

When we really want users to complete a field, we can use placeholders to prompt a question for users to respond to. This should be direct and in the second person, and should have a simple, short answer.

```usage
<Usage type="yes">
### Yes
- What do you want to cook tonight?
</Usage>
```

### Categories

When the response to an input field might be from a wide range of options, placeholders can be used to reduce the number of choices and provide guidelines for how to respond to the field.

```usage
<Usage type="yes">
### Yes
- Filter recipes by protein, cuisine
</Usage>
```

### Examples

Sometimes, an example will make it easier for users to understand how to answer a field.

```usage
<Usage type="yes">
### Yes
- Such as “Leave inside box at side of house”
</Usage>
```

## Helper messages

Sometimes, our users need a bit of help. Helper messages help us support our users when they’re filling out forms or taking an action.

Some specific guidelines for writing helper messages:

### Do users need help?

Before adding helper messages, ask whether users actually need help. The more messages we include on a page or form, the more intimidating it appears to our users.

### Be concise

This is particularly important for helper messages on input fields.

```usage
<Usage type="yes">
### Yes
- 8–12 characters.
</Usage>
<Usage type="no">
### No
- Password must be between 8–12 characters.
</Usage>
```

## Push notifications

- ``TODO``

## Email notifications

- ``TODO``

Actionable language


We have an editorial style for our digital products to help us keep our copy clear and consistent, and specific guidelines to write and structure content to make it easy for users to understand and act on.

## Abbreviations & acronyms

Avoid abbreviations and acronyms when possible.

```usage
<Usage type="yes">
### Yes
- for example
</Usage>
<Usage type="no">
### No
- e.g.
</Usage>
```

## Adverbs and adjectives

Try to avoid adjectives and adverbs. Using adjectives and adverbs (for example, “easy” recipe) shapes perception and sets expectations, and can inadvertently lead to a negative emotional experience for our customers. 

If someone is new to cooking and feels nervous about their abilities, then describing a recipe as “easy” can help them choose that recipe. But if they have trouble cooking it, they may feel bad because the recipe was supposed to be “easy,” and they still had trouble.

Instead, look for opportunities to capture the same meaning through other forms. What makes an “easy” recipe easy relative to other recipes? Can that be used as a scale of relative difficulty?

## Active voice vs. passive voice

Use active voice and avoid passive voice. In active voice, the subject of the sentence does the action. In passive voice, the subject of the sentence has the action done to it.

```usage
<Usage type="yes">
### Yes
- Added recipe to box.
</Usage>
<Usage type="no">
### No
- The recipe was added to box.
</Usage>
```

Use passive voice when you don’t want to assign responsibility for an action. This can reduce tension in a message.

```usage
<Usage type="yes">
### Yes
- Delivery address was incorrect.
</Usage>
<Usage type="no">
### No
- Wrong delivery address provided.
</Usage>
```

## Present tense

Use present tense to describe the result of actions.

```usage
<Usage type="yes">
### Yes
- Recipe added
</Usage>
<Usage type="no">
### No
- Recipe has been added
</Usage>
```

## Capitalization

We use different forms of capitalization depending on the context.

For example, use title case for recipe names and weekly status messages, and use sentence case for recipe steps. If you’re not sure which capitalization to use, check the design system for existing conventions.

All-caps should be used sparingly and only for specific purposes. Never use all-caps within a sentence. 

## Contractions

Use contractions like “we’ll” or “there’s!” They make our writing more conversational. 

However, don’t rely on contractions alone for a conversational voice. When we translate copy for our global audience, they almost won’t carry over.

## Conversational writing

Our voice is conversational. When we’re talking, we connect words with articles like “the,” “for,” “these,” and “an.” If we remove these from our writing, it makes our copy feel stiff and complicated. We can be flexible, though. If space is a limitation, the article can be omitted.

```usage
<Usage type="yes">
### Yes
- Choose a recipe
- Save your changes
</Usage>
<Usage type="no">
### No
- Choose recipe
- Save changes
</Usage>
```

## Avoid directional language

Avoid any instructions or language that requires the user to see the layout or design of a page or element.

```usage
<Usage type="yes">
### Yes
- Choose a new delivery time.
</Usage>
<Usage type="no">
### No
- Choose a new delivery time at the bottom right of this page.
</Usage>
```

## Numbers

Use the numeral when numbers appear in copy. This includes ordinals (numbers that tell the position of something in a list).

```usage
<Usage type="yes">
### Yes
- You have 3 meals in your box
- 2 days left to make changes
- This is your 3rd box
</Usage>
<Usage type="no">
### No
- You have three meals in your box
- Two days left to make changes
- This is your third box
</Usage>
```

When writing in English, numbers over 3 digits get commas.

```usage
<Usage type="yes">
### Yes
- 144
- 1,200
</Usage>
```

When writing in German, Swedish, and Dutch, numbers over 3 digits get a period.

```usage
<Usage type="yes">
### Yes
- 144
- 1.200
</Usage>
```

### Dates

Spell out the day of the week and the month whenever possible. Abbreviate when space is a limitation. When abbreviated in interface headings and labels, do not use a period.

The order of day and month should match the user’s locale.

```usage
<Usage type="yes">
### Yes
- **USA:** Thursday, April 16
- **USA:** April 16
- **USA:** Apr 16
- **Germany:** Thursday, 16 April
- **Germany:** 16 April
- **Germany:** 16 Apr
</Usage>
```

When possible, use natural language to describe dates.

```usage
<Usage type="yes">
### Yes
- Today
- Yesterday
- Tomorrow
- This week
- Next week
- Two weeks from now
</Usage>
```

### Fractions

Use typographic fractions when referencing measurements in ingredients. Don’t spell fractions out.

```usage
<Usage type="yes">
### Yes
- ½
</Usage>
<Usage type="no">
### No
- 1/2
- one-half
</Usage>
```

### Percentages

Use the % symbol instead of spelling out “percent.”

```usage
<Usage type="yes">
### Yes
- 2%
</Usage>
<Usage type="no">
### No
- Two percent
</Usage>
```

### Ranges and spans

Use an en dash (`–`) to indicate a range or span of numbers. Do not use spaces before and after the en dash.

```usage
<Usage type="yes">
### Yes
- Cook for 10–20 minutes
</Usage>
```

An en dash is slightly wider than a hyphen (`-`) but narrower than an em dash (`—`).

### Money

When writing about US or AU currency, use the dollar sign ($) before the amount. Always include a decimal and number of cents. Do not insert a space between the dollar sign and the number.

```usage
<Usage type="yes">
### Yes
- $10.00
- $42.99
</Usage>
```

When writing about EUR currency, use the Euro sign (€) after the amount. Always include a comma and number of cents. Insert a space between the number and the Euro sign.

```usage
<Usage type="yes">
### Yes
- 10,00 €
- 42,99 €
</Usage>
```

### Telephone numbers

Use dashes without spaces between numbers. Don’t use a country code.

```usage
<Usage type="yes">
### Yes
- 866-228-4513
- 030-208-480-510
- 02-6145-2910
</Usage>
```

### Temperature

Use the degree symbol and capital C abbreviation for Celsius (everywhere except the USA) or capital F abbreviation for Fahrenheit (USA only). Don’t insert spaces between the number and the abbreviation.

```usage
<Usage type="yes">
### Yes
- 220°C
- 425°F
</Usage>
```

### Time

When writing about a time of the day, use numerals and lowercase am or pm, with a space in between. Use 12- or 24-hour time according to the locale. When writing in 24-hour time, show a `0` before single-digit hours. 

```usage
<Usage type="yes">
### Yes
- 5 pm
- 8:30 pm
- 06:30
</Usage>
<Usage type="no">
### No
- 5pm
- 8:30PM
- 6:30h
</Usage>
```

Use an en dash (`–`) between times to indicate a time period. Don’t insert spaces before and after the en dash.

```usage
<Usage type="yes">
### Yes
- 8 am–12 pm 
- 06:30–18:00 
</Usage>
```

When referring to an amount of time, use numerals and the full word, with a space in between.

```usage
<Usage type="yes">
### Yes
- Cook for 20 minutes.
- Steam for 30 seconds.
</Usage>
```

### Units of measurement

In all cases, include a space between the number and the unit of measurement.

```usage
<Usage type="yes">
### Yes
- 100 g
</Usage>
<Usage type="no">
### No
- 100g
</Usage>
```

## Punctuation

### Apostrophes

Apostrophes are usually used to make a word possessive. If the word already ends in an s and it’s singular, you also add an’s. If the word ends in an s and is plural, just add an apostrophe.

Watch out for dumb apostrophes (`'`). These are a relic of typewriters, and can be identified by how they’re straight rather than curly. Always use typographic apostrophes (`‘`).

```usage
<Usage type="yes">
### Yes
- This recipe’s best cooked within 3 days.
- This recipe is Martha’s favourite.
- Chris’s favourite recipe
</Usage>
```

### Colons

Use a colon to offset a list.

```usage
<Usage type="yes">
### Yes
- Gather three things before starting: pots, pans, and knives.
When a list begins with an interface label, capitalize the first word of the list.
- Allergens: Dairy, peanuts, and anchovies.
</Usage>
```

### Commas

Use the Oxford comma when writing a list.

```usage
<Usage type="yes">
### Yes
- Allergens include dairy, peanuts, and anchovies.
</Usage>
<Usage type="no">
### No
- Allergens include dairy, peanuts and anchovies.
</Usage>
```

### Dashes and hyphens

Use a hyphen (`-`) without spaces before and after to link words into a single phrase.

```usage
<Usage type="yes">
### Yes
- First-time cook?
</Usage>
```

Use an en dash (`–`) to indicate a [range or span](#ranges-and-spans), without spaces.

```usage
<Usage type="yes">
### Yes
- Cook for 10–20 minutes
</Usage>
```

Use an em (`—`) dash without spaces to separate clauses in paragraph copy.

```usage
<Usage type="yes">
### Yes
- Our new smoothies—you’ll be delighted to hear—are perfect for gluten-free diets.
</Usage>
```

### Ellipses

Use ellipses to indicate that a line of copy has been clipped before the end. This is typically used when only a single line of copy will fit, but the content itself is too long. Avoid this when possible.

When ellipses are used to clip a line of copy, clip after at least 2 characters.

```usage
<Usage type="yes">
### Yes
- Free-Range Heritage Chicken With Sc…
</Usage>
<Usage type="no">
### No
- Free-Range Heritage Chicken With S…
</Usage>
```

### Periods

Use periods in complete sentences. Don’t use periods in headlines or labels. Periods go inside quotation marks. They go outside parentheses ( ) when the contained text is part of a larger sentence, and inside when the contained text stands alone.

```usage
<Usage type="yes">
### Yes
- 3 meals in your box
- Your delivery was rescheduled to Tuesday because of a holiday (St. Patrick’s Day).
</Usage>
<Usage type="no">
### No
- 3 meals in your box.
</Usage>
```

### Quotation marks

Watch out for dumb quotation marks (`'` and `"`). These are a relic of typewriters, and can be identified by how they’re straight rather than curly. Always use typographic quotation marks (`‘` and `’`, `“` and `”`).

```usage
<Usage type="yes">
### Yes
- ‘Example’
- “Example Two”
</Usage>
<Usage type="no">
### No
- 'Example'
- "Example two"
</Usage>
```

## Places

Spell out all city names. 

When written in paragraph copy, write out country, state, and province names on the first mention. On subsequent mentions, abbreviating is fine.

```usage
<Usage type="yes">
### Yes
- Now available in Sweden.
</Usage>
<Usage type="no">
### No
- Now available in SWE.
</Usage>
```

## Positive vs negative

Use positive language rather than negative language. Positives are easier to read and process than negatives. One way to detect negative language is to look for words like “can’t,” “don’t,” etc.

```usage
<Usage type="yes">
### Yes
- Update your payment method to get your box.
</Usage>
<Usage type="no">
### No
- If you don’t update your payment method, you won’t get your box.
</Usage>
```

## Use positive words when talking about positive things

If a sentence begins with a negative word, the sentence’s implication can be misinterpreted as negative.

```usage
<Usage type="yes">
### Yes
- Remember to save your new payment method
</Usage>
<Usage type="no">
### No
- Don’t forget to save your new payment method
</Usage>
```

## Writing questions

A common error when writing questions is not constructing the sentence as a question. Usually, this can be fixed by changing the word order.

```usage
<Usage type="yes">
### Yes
- Why should meat and vegetables be chopped on separate cooking boards?
</Usage>
<Usage type="no">
### No
- Why meat and vegetables should be chopped on separate cooking boards?  
</Usage>
```

## Writing about ourselves

We have a few different names depending on whether we’re referring to our legal entity or our trade name, and which market we’re writing for.

In our digital products, use our trade name for each market:

```usage
<Usage type="yes">
### Yes
- **EU:** Marley Spoon
- **US:** Martha & Marley Spoon, Dinnerly
- **AU:** Marley Spoon, Dinnerly
</Usage>
```

Always title case our name. Don’t abbreviate our name.

```usage
<Usage type="yes">
### Yes
- Martha & Marley Spoon
</Usage>
<Usage type="no">
### No
- Martha & Marley spoon
- MMS  
</Usage>
```

Don’t capitalize descriptive product or feature names.

```usage
<Usage type="yes">
### Yes
- our mobile app
- taste profile
- your box
</Usage>
<Usage type="no">
### No
- our Mobile App
- Taste Profile
- your Box
</Usage>
```

## Writing about people

We design and build our platforms with a human-centered point of view. Whenever we write something for our digital platforms, we need to write in a way that’s compassionate, inclusive, and respectful.

Here are some specific guidelines for how we write about people.

### Disability

Avoid disability-related idioms like “lame” or “falling on deaf ears.”

Default to person-first language rather than identity-first language.

```usage
<Usage type="yes">
### Yes
- they have a disability
- person with disability
- people living with disabilities
</Usage>
<Usage type="no">
### No
- they are disabled
- disabled person
</Usage>
```

Do not use the term “edge cases” to describe users living with disabilities. This term further marginalizes people already living on the margins. Instead, use the term “stress cases.”

### Gender and sexuality

Don’t call groups of people “guys.” Don’t call women “girls.” `(Quoting from Mailchimp)`

Avoid gendered terms.

```usage
<Usage type="yes">
### Yes
- Deliveryperson
</Usage>
<Usage type="no">
### No
- Deliveryman
</Usage>
```

``TODO How does the adapt to other languages like German?``

It’s okay to use “they” as a singular pronoun.

### Hearing

Use lower-case “deaf,” “hard of hearing,” or “hearing loss” as adjectives to describe someone with hearing loss.

### Vision

Use lower-case “blind” to describe someone who is unable to see. Use “low vision” or “vision loss” as adjectives to describe a person with limited vision.

## Avoid words with multiple meanings

Some words to watch out for:

**Once** (could mean “one time,” “after,” “in the past,” or “when”)

```usage
<Usage type="yes">
### Yes
- After you’ve made your choices
</Usage>
<Usage type="no">
### No
- Once you’ve made your choice
</Usage>
```

**Right** (could mean “correct,” “the opposite of left,” “politically conservative,” etc.)

```usage
<Usage type="yes">
### Yes
- Pick the right recipe
</Usage>
<Usage type="no">
### No
- Pick the recipe you like most
</Usage>
```

**Since** (could refer to a point in time, or a synonym of “because”)

```usage
<Usage type="yes">
### Yes
- Because you have a referral already, you can invite a friend to get a free box
</Usage>
<Usage type="no">
### No
- Since you already have a referral, you can invite a friend to get a free box
</Usage>
```

**“Require” plus an infinitive** (could confuse the relationship between subject and object)

```usage
<Usage type="yes">
### Yes
- Referrals can be sent from any Marley Spoon account.
</Usage>
<Usage type="no">
### No
- A Marley Spoon account is required to send referrals. _(This could imply that both the sender and receiver have to have a Marley Spoon account to send a referral.)_
</Usage>
```

## Avoid idioms

In most languages, idioms are commonly-known phrases packed with meaning. However, idioms don’t often translate into other languages. They can also create confusion for translators that have English as an additional language.

```usage
<Usage type="yes">
### Yes
- `TODO`
</Usage>
<Usage type="no">
### No
- `TODO`
</Usage>
```

Style & mechanics


From time to time, we need to share messages with our users through our app and digital platforms about a variety of things. Our challenge is that not all messages are equal, and we need to communicate with our users in the right way at the right time for any given message.

Since “the right way at the right time“ is somewhat subjective, we’ve created a framework to make it easy to consistently choose the right way to share messages, and to make it simple to plan in-app communications for larger ongoing initiatives.

## Types of messages

We have three types of messages, in level of priority:


1. Interrupt
2. Contextual
3. Independent

Each type of message is supported in the mobile app in a few different ways.

## 1. Interrupt

An Interrupt does just that: interrupts whatever the user is currently trying to do, and prevents them from returning to their original goal until they do something about it.

### How the user interacts with an interrupt:

The user must **acknowledge** the interruption by either:

- Dismissing or closing the interruption
- Taking an action provided by the interruption

### When to use:

- Should be used with great restraint: by their very nature, interrupts get in the user’s way!
- The **positive benefit** of interrupting the user must always be greater than the **negative experience impact** of interrupting the user. Don’t underestimate the negative impact, or the cumulative “banner blindness” that users will develop if they’re frequently interrupted with information that **they** don’t value!

### What it looks like:

- Usually takes the form of a **takeover** in the mobile app.
- A more moderate interrupt is a **push notification**.

## 2. Contextual

A contextual message appears within something that it has a direct relationship with. user’s goal or location within the app. Any given message relies on the context that it appears within.

### A contextual message:

- Should provide direct and obvious value to both the user and business in terms of information provided or outcomes as a result of the message.
- Can have many forms, each tightly integrated into the context in which they belong. Can be both **active** (supports user interaction) or **passive** (provides information but no action available). When active, can result in **immediate outcome** or act as an **in-between** to direct users towards another context to accomplish a goal.

## 3. Independent

Can appear outside of a given context, and does not require any interaction. Primarily informative and provides additional depth.

### An independent message:

- Should (usually) not be strongly tied to app or experience performance metrics, as it is not intended to strongly drive behavioural outcomes.

### What it looks like:

- Can be a static or carousel-style message in the app, independent of its context.
- Email is usually independent.

## Message Planning

By using a simple three step process, it’s easy to plan how to communicate any given message or campaign throughout the app, in a way that will help us achieve our goals, help our users achieve their goals, and result in the best user experience outcomes.

1. Identify behavioural outcome.
2. Identify timeline and key moments.
3. Identify message priority for each key moment with the prioritization matrix.

### 1. Identify behavioural outcome

What user action or behaviour do we want to use to say “**this message did what it was supposed to do?**“

Different kinds of messages have different desired behavioural outcomes. Some examples:

- If an ingredient needs to be recalled due to a food poisoning event, the behavioural outcome is “**acknowledged recall notice.**”
- If we want users to provide a review for a recipe, the behavioural outcome is “**provided a rating.**”
- If a box’s normal delivery day is automatically changed due to a holiday on their regular delivery day, the behavioural outcome is “**engages with box**” (so that we are confident they are aware the day changed). In this case, “engaging with box” could mean that they’ve viewed the box in the “Upcoming” tab (mobile app), viewed the menu for that box (web platform), or even opened an email with information about the shifted delivery day.

### 2. Identify timeline and key moments

For any given topic or theme, it’s likely the urgency or potential impact of the message changes over time.

Take, for example, how we might approach messaging around someone’s normal delivery day automatically changing due to a holiday on their regular delivery day. We’ve already defined the behavioural outcome as “engages with box.”

- Three weeks before their box cutoff date, it’s not necessarily all that pressing if they don’t engage with the box.
- Three days before their box cutoff, it’s starting to get worrying if they don’t engage with the box. If they don’t realize their delivery day has changed, they might get a box when they don’t expect to, and that could either leave them hungry or surprise them in a not-so-great way when it arrives early.
- The day before cutoff, if they still haven’t engaged with the box, we should be rightfully worried. We don’t want our customer to be surprised, because that’s a poor user experience and might result in losing a valued customer.

Based on this series of events, we can say that there’s three key moments in the “automatically changed delivery day due to holiday” messaging.

1. Three weeks before cutoff
2. Three days before cutoff
3. One day before cutoff

Sometimes, there may not be any timeline associated with a message. If we have to recall an ingredient due to a food poisoning event, it’s likely to be a one-time thing. If we want users to provide a rating for something they’ve cooked, it’s likely to be a regular and constant thing. That’s fine too! Then, each message simply has a single key moment when it becomes relevant.

### 3. Identify message priority for each key moment with the prioritization matrix

With key moments in hand, the next step is to identify the message priority with the prioritization matrix. This is very easy to use.

First, consider the **impact** of the message in that key moment, for both the user and the business.
Second, consider how **urgent** the message is in that key moment.

Then, place the key moment into the prioritization matrix. Each space in the matric directly maps to a type of message!

``TODO Add image of matrix``

If you’re having trouble placing a moment into the matrix, consider whether the moment needs more context.

## Calibrating over time

By the very nature of having a framework like this, we’ll be able to improve our prioritization over time, because we can document all existing and past messages into the prioritization matrix, and use that to “calibrate” our own evaluations of urgency and impact.

## Building consensus

The matrix is also a good way to build consensus on a team. Consider having each member of the team independently place a given message or messages into the matrix based on their own judgement, without seeing other member’s placements. Then, compare the combined placements and use that as a basis for discussion.

Prioritising and message placement


We use certain words in a special way. This glossary defines our terminology to make sure we all use the same words for the same things.

The list below includes ~~deprecated~~ terms that are either ambiguous or obsolete and should be replaced with the ~~corresponding~~ → **preferred term**.

`TODO: This word list will be updated with definitions and equivalent terms for each language.`

## Things
- account
- plan
    - meals per week
    - number of servings per meal
- delivery week
- delivery day
- delivery time
- delivery address
- box
- menu
- recipe
    - tag
    - cooking step
    - timer
    - ingredient
        - in your box
        - what you’ll need
    - kitchen equipment
    - allergen
    - nutrition information
- ~~portion~~ → **serving**
- meal
- rating
- review
- payment method
- pause
- voucher
- credit
- refund
- `TODO: more to be added based on expanded product offerings workshops`

## Verbs

`TOOD: This word list will be updated with details around when to use which verb.`

- OK vs. accept
- Close vs. cancel
- Done vs. back vs never mind
- Choose vs. select
- Edit vs. manage
- Choose vs. swap
- Swap vs. switch
- View vs. see
- Need vs. must
- Export vs. download
- Share vs. refer


## Tricky words
- addon (noun, adjective), add on (verb)
- email
- homepage
- login (noun, adjective), log in (verb)
- OK
- opt-in (noun, adjective), opt in (verb)
- never mind (verb)
- signup (noun, adjective), sign up (verb)
- username
- URL
- website

## Avoid these words

**Once** (could mean “one time,” “after,” “in the past,” or “when”)

```usage
<Usage type="yes">
### Yes
- After you’ve made your choices
</Usage>
<Usage type="no">
### No
- Once you’ve made your choice  
</Usage>
```
    
**Right** (could mean “correct,” “the opposite of left,” “politically conservative,” etc.)

```usage
<Usage type="yes">
### Yes
- Pick the recipe you like most  
</Usage>
<Usage type="no">
### No
- Pick the right recipe
</Usage>
```

**Since** (could refer to a point in time, or a synonym of “because”)

```usage
<Usage type="yes">
### Yes
- Because you have a referral already, you can invite a friend to get a free box
</Usage>
<Usage type="no">
### No
- Since you already have a referral, you can invite a friend to get a free box  
</Usage>
```
    
”**Require**” plus an infinitive

```usage
<Usage type="yes">
### Yes
- Referrals can be sent from any Marley Spoon account.
</Usage>
<Usage type="no">
### No
- A Marley Spoon account is required to send referrals. _(This could imply that both the sender and receiver have to have a Marley Spoon account to send a referral.)_
</Usage>
```

**Fresh** (avoid words owned by competitors)