Skip to main content
Menu

Writing for products

On this page

Writing for products

Writing for products isn't difficult when you remember that your interface is a conversation with your users. Try and replicate human conversation as much as possible and respect people's time to explain things simply and clearly.

Low reading age

Re-read your work and replace any words that have a simpler alternative

Do
Writing for a low reading age isn't about dumbing stuff down it's about respecting your user's time.
  • Buy
  • Get
Don't
Content with a higher reading age (for example, longer words) takes longer to understand.
  • Purchase
  • Receive

Keep sentences short and avoid complex structure

Do
Grade: 6
dApp only works on the Main Ethereum network. Switch networks in your MetaMask extension to continue. You’re currently using Ropsten, a test network that doesn’t use real funds.
Don't
Grade: 8
dApp only works on the Main Ethereum network but you're using Ropsten, a test network that doesn’t use real funds. Switch networks in your MetaMask extension to continue.

A quick way to check your content's reading age is hemingwayapp.com

See usability evidence on short sentences

Jargon excludes

The more jargon you use in your product the more users you're likely to exclude from the conversation. Your interface is a conversation with your users, it should teach them how to use and derive the most benefit from your product. By using jargon, you're forcing them to learn another language just to understand the main conversation!

Avoid words like:

  • Protocol
  • Web3 provider

Look for overly technical words

Do
Replace system language with human words you'd use in conversation
Choose
Don't
Technical terms and system langauge can feel less natural. Are you more like to use 'Select' or 'Choose' in a sentence?
Select

See usability evidence on the benefits of avoiding jargon

Use an active voice

Do
An active voice prevents your dapp from sounding like a textbook and more like you're talking to a human being. It will also help keep your content more direct, succinct and shorter. Plus it tends to inject some pace and even inspire action – CTAs are always written in an active voice.
  • You need Ether for this transaction
  • You got a Cryptokitty from 0x1234...5678
  • Enter a description
Don't
A passive voice sounds more robotic and creates ambiguity around who is doing what.
  • Ether is required to complete this transaction
  • Cryptokitty was received from 0x1234...5678
  • A description is needed

is and was are usually good signs you're writing passively.

See usability evidence on using the active voice

Avoid system terms

Do
Refer to things using the language you'd use in conversation or in real life. Ask yourself, have you ever submitted a transaction in real life?
  • Sending your ETH
  • Casting your vote
  • You bought a Cryptokitty
Don't
Generalising everything as a transaction undermines the breadth of things Ethereum allows us to do in a decentralized way.
  • Processing your transaction
  • Your transaction was successful

Sell benefits, not technology

If Facebook was a blockchain company:

Facebook is a social network that uses PHP, compiled with HipHop for PHP and a "source code transformer" that turns PHP into C++

Adoption won't come from explaining the technology behind your dapp. Most people don't understand how cloud technology works, they just know they can access their files anywhere, from any device. That's because we've been delivered the benefits time and time again. Talk about what your product does for people, not how it was architected. Technology backs up benefits and provides proof points, not selling points.

Do
Reference benefits before technology.
With [dApp] you can manage all your data from one safe place
Don't
Technology is rarely a reason to use an application.
[dApp] is an all-in-one data management platform using IPFS