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)