index.md

title	description	lang
Style Guide	Style guide for ethereum.org	en

Ethereum.org style guide {#style-guide}

Content on ethereum.org is crowdsourced and primarily written by our incredible contributors.

Our primary objective is to educate and inform visitors about Ethereum in a manner that is accessible to a diverse range of readers, from technical experts to casual visitors. Since we deal with complex and abstract topics, clear content writing is crucial to effectively convey the information and avoid confusion or misinterpretation.

You should read this style guide before you contribute to ethereum.org.

Who can submit content to ethereum.org {#who-can-help}

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 {#audience}

• 60% of our website visitors do not own any ether according to our survey responses
• 50% of visitors identify themselves as newcomers to the crypto space

Common reading-related problems:

• Articles are hard to digest due to
  • too much text per page / paragraph
  • usage of complex sentences
  • technical jargon
• Content is too abstract and detached from reality, therefore users are unable to relate to it
• Too many links inside articles result in readers feeling overloaded and leaving the website

Takeaways:

• Operate with a mindset that people are curious about crypto, but not invested enough to spend hours exploring the topics
• Users want to understand how the topic relates to them and how they can take a part in it rather than going deep into the theory

Loosely we can categorize the site audiences as:

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"

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"

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"

Best practices {#best-practices}

Style

• Focus on the advantages for the user instead of explaining technical details about the system
• Use active voice and clear, concise sentences that are easy to follow
• Break up longer chunks of text into smaller sections or paragraphs
• Consider using tables, bullet points or numbered lists instead of paragraphs
• Highlight (bold) key phrases to support scanning and skimming through the article

Content ideas:

• Use examples or real-life scenarios of the application of the technology to help illustrate complex concepts or ideas
• Explain how the idea can positively affect people now or in the future
• Create before Ethereum / after Ethereum comparison
• Add step-by-step how to take action
• Include relevant statistics or graphs to strengthen the arguments
• Add calls to action
• Provide visual aids to explain the topic better

Other:

• Limit the length of the article up to 1000 words (1500 max)
• Reduce the number of hyperlinks to approximately 5 per 1000 words (excluding further reading section at the bottom of the page or product listings)

Objectivity {#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..."

Acronyms {#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 {#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.

Content standardization - Read more about proper usage of terminology and other aspects such as how to properly add an image, attribute etc.

Anything else? {#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.