Imagine you’re addressing users
Use “we” for Contentful, “you” for users and “let’s” for instructions e.g. onboarding. This is an engaging and friendly way of writing. Use “my” to infer ownership e.g “my account”.
✅ We chose a space name for you.
🚫 A name was chosen for the space.
Use let’s for onboarding
✅ Let’s start by selecting the add release button.
🚫 To get started the add release button should be selected.
Never command users with words like “must”, instead gently nudge
✅ Log in before editing.
🚫 You must log in before editing.
Begin with the most important information
Try to front load sentences with the most important information. This could be the goal, action to take or benefit to users. This makes content easier to scan.
Write the action the user needs to take at the beginning of the sentence
✅ To view your content in a live environment, set up content preview.
🚫 Set up content preview to view your content in a live environment.
✅ Unpublish the entry before deleting.
🚫 To delete an entry, you have to first unpublish it.
Focus on the value to the user
✅ Easily schedule your content releases with Launch.
🚫 Launch allows you to easily schedule your content releases.
Inform on a need-to-know basis
Use bite sizes of information. It can be tempting to add more explanation, but less is more. You can tell them more when they need to know. Some information is implied and does not need to be stated.
✅ We’ll help you choose a plan that fits your needs.
🚫 We'll review outcomes and help you choose a plan that fits your needs.
✅ Once you publish changes to this entry, you can view all previous versions.
🚫 There are no previous versions because you haven't made changes to this entry yet. As soon as you publish changes, you'll be able to compare different versions.
Write. Short. Sentences.
Try to stick to one idea per sentence. Breaking up the message makes it easier to understand.
✅ Carefully add or remove tags. You could unintentionally give or remove anyone’s access to this entry, including yours.
🚫 Be careful when you add or remove tags as you could unintentionally remove or give access to this entry to anyone in this space.
Put jargon in the bin
Pretend the user has little understanding of the product. Jargon can exclude people from the conversation.
❌ Avoid words like: utilize, disclosure, nominated, transitioned, embargoed, enabled
✅ We’ll email you the invoice if you have extra charges.
🚫 If additional charges are applicable, you will be sent an invoice at your nominated email.
Use delight and humour to distract from a negative action or amplify a positive one
The secret to delightful copy is to give your users a nice surprise! But it’s not always appropriate. Appropriate in:
- Loading states
- Empty states
- Success messages
- Placeholders and examples
- Onboarding flows
- Error messages (not critical or serious ones) Be witty, but never at the expense of the message. Will people still understand the message?
✅ Puns, dad jokes, word play, universally understandable
🚫 Sarcasm, rude jokes, in-jokes (like memes)
Examples
