Help update this page


There’s a new version of this page but it’s only in English right now. Help us translate the latest version.

Page last updated: September 18, 2021 Style Guide

Content on is crowdsourced and primarily written by our incredible contributors. This style guide aims to standardize certain aspects of writing content to make the contribution process smoother.

You should read this style guide before you contribute to

Who can submit content to

Anyone! is entirely open source, and many of its best pages are submitted by curious learners who expanded their notes into documentation pages now living on the site.

Audience content caters to a large and varied audience. Because caters to a wide spectrum of users, all content on the site should make an effort to explain any technologies and concepts as simply as possible.

Loosely we can categorize the site audiences as:


App users, investors, enthusiasts, or anyone who is "new to Ethereum".

Example user journeys:

  • "I want to learn more about Ethereum, to know if I think it’s credible or not. Once I’ve answered a few basic questions, I want to try using Ethereum"
  • "I know I need an Ethereum wallet, and want a good recommendation"
  • "I want to learn how to run an Ethereum node"
  • "I want to get a sense of the size and activity of the Ethereum community, to decide if it's active enough, so I can get help if needed"
  • "I’m excited about Ethereum and want to get involved, but I don’t know what to do next"


Developers or others who want technical information about Ethereum.

Example user journeys:

  • "I'm a developer but I have no background in crypto and want to understand the Ethereum tech stack at a high level"
  • "I want to get a sample Ethereum project up and running fast, to get a sense of how difficult or easy it is to build a real project on Ethereum"
  • "I want to learn about Ethereum's technical roadmap"
  • "I’ve started work on an Ethereum project, and want to try out a few smart contract testing libraries"


People, businesses, and other organizations who want to understand Ethereum's value in an enterprise setting.

Example user journeys:

  • "I want to understand what use cases Ethereum can help with, and how it compares to other chains or other technologies"
  • "I work at a business that is beginning an Ethereum related project, and want to learn more"
  • "I want to understand the differences between private Ethereum chains, consortium chains, and the public Ethereum Mainnet"
  • "I want to know the current status of Ethereum - how long has it been in production, how much usage it has, what's the direction of new development - to decide if I am confident to build my project on top of it"

Objectivity documentation (and content at large) aims to maintain a credibly neutral source of truth to inform readers about Ethereum and its ecosystem. Some examples of things that we don't want in the content on

Grand, unverifiable claims about Ethereum or adjacent technologies

e.g. "Ethereum will take over the world because..."

Hostile or confrontational language aimed at any organization or person

e.g. "Company X is bad because they are centralized!"

Politically charged rhetoric

e.g. "This political party is better for decentralization because..."


The tone of the content on the site should be welcoming, friendly and straightforward. Jargon should be minimized and simple language used instead.

Read the design principles for more on direction tone.

Best Practices

Use American English

For words that have multiple spellings, use American English over British English.

For example:

  • "decentralized" over "decentralised"
  • "color" over "colour"
  • "analyze" over "analyse"


When introducing an unfamiliar acronym, spell out the full term, and put the acronym in parentheses. Put both the full term and acronym in bold.

For example:

"Ethereum, like Bitcoin, currently uses a consensus protocol called proof-of-work (PoW)."


Many of the topics covered on are technically complex. To reduce confusion to the reader, terms should be used consistently. For example, don't cycle back-and-forth between proof-of-work and PoW at random.


Ethereum is a proper noun and should always be capitalized.

  • "Ethereum" not "ethereum"


Ether is a common noun and should not be capitalized unless at the beginning of a sentence. ETH, on the other hand, is a currency abbreviation (and ticker symbol) and should always be capitalized.

  • "ether" not "Ether"
  • "ETH" not "eth or Eth"


When referring to the Ethereum Mainnet (i.e. not referring to a testnet) use the proper noun. Proper nouns help avoid confusion and build greater understanding.

Correct usage:

  • Mainnet
  • Ethereum Mainnet

Incorrect usage:

  • main net
  • mainnet
  • Main net
  • Ethereum mainnet

Proof-of-work / Proof-of-stake

Proof-of-work should be capitalized at the beginning of a sentence. In any other instance, all letters should be lower case. In either case, proof-of-work should be hyphenated between each word.

Correct usage:

  • Proof-of-work
  • proof-of-work

Incorrect usage:

  • Proof-of-Work
  • Proof of work
  • proof of work

The same rules we apply to proof-of-work are applicable to proof-of-stake, proof-of-authority, proof-of-humanity, proof-of-individuality, etc.

Use Active Voice

Sentences using active voice are more concise and efficient, making your writing more engaging and easier to comprehend.

Active voice sentence: an actor acts on a target

"The man bought a car."

Passive voice sentence: a target acts on an actor

"The car was bought by a man."

Read more on active voice

This isn't an easy one, especially for non-native English speakers. If you aren't sure, don't worry. We'll help with any of these.

When linking to another page on, use the relative path over the absolute path. Do not hard-code the language path (i.e. /en/) in any links. This maintains consistent functionality across different language versions of the site.

<!-- Good -->

Read more about [smart contracts](/docs/developers/smart-contracts/)

<!-- Bad -->

Read more about [smart contracts](/en/docs/developers/smart-contracts)
Read more about [smart contracts](

Please also add a trailing slash to all links. This keeps links consistent and avoids redirects, which hurts site performance.

<!-- Good -->

Read more about [smart contracts](/docs/developers/smart-contracts/)

<!-- Bad -->

Read more about [smart contracts](/docs/developers/smart-contracts)

Linking to images

When adding an image to a page, the image should be downloaded and placed in the same folder as the markdown file. You can reference the image like this:

![alt text for image](./image.png)

<!-- Good -->

![How to mint your NFT](./mintYourNFT.gif)

<!-- Bad -->

![How to mint your NFT](

This helps us ensure the image will be available.

Using Emojis

Everyone loves emojis 🥰 To standardize the appearance of all Emojis across browsers, uses an <Emoji /> React component.

<--- Good --->

The London Upgrade is live <Emoji text=":heart:" size={1} />

The London Upgrade is live <Emoji text="❤️" size={1} />

<--- Bad --->

The London Upgrade is live ❤️

Anything else?

Like all content on, this style guide is an open-source work-in-progress with room for improvement. If there is anything you think should be added to improve this document please suggest an edit on GitHub.