Ethereum.org 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
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
- 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:
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
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
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.
Content standardization - Read more about proper usage of terminology and other aspects such as how to properly add an image, attribute etc.
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(opens in a new tab).