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

Ethereum.org Style Guide

Content on ethereum.org 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 ethereum.org.

Who can submit content to ethereum.org

Anyone! Ethereum.org 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

Ethereum.org content caters to a large and varied audience. Because ethereum.org 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:

Individuals

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

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"

Enterprises

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

Ethereum.org 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 ethereum.org:

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..."

Tone

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 ethereum.org 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"

Acronyms

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)."

Consistency

Many of the topics covered on ethereum.org 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

Ethereum is a proper noun and should always be capitalized.

  • "Ethereum" not "ethereum"

Ether

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"

Mainnet

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 Ethereum.org, 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](https://ethereum.org/en/docs/developers/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](https://cdn-images-1.medium.com/max/2000/0342fj_fsdfs.gif)

This helps us ensure the image will be available.

Using Emojis

Everyone loves emojis 🥰 To standardize the appearance of all Emojis across browsers, ethereum.org 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 ethereum.org, 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.