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

Writing for a low reading age isn't about dumbing stuff down it's about respecting your user's time. Content with a lower reading age is easier and quicker to understand.

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

  • Buy
  • Get
  • Purchase
  • Receive

Keep sentences short and avoid complex structure

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.
Grade: 6
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.
Grade: 8

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 or system language and replace with more human words you'd use in conversation


See usability evidence on the benefits of avoiding jargon

Use an active voice

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
  • 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

There's a habit in the community of just referring to everything as a transaction. But the beauty of Ethereum is the breadth of things it allows us to do in a decentralized way. Generalising everything as a transaction undermines that. 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
  • 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.

With dapp you can manage all your data from one safe place
dapp is an all-in-one data management platform using IPFS

Are we missing anything?

If you have any extra insight you'd like to add, please raise an issue in Github.