The following are writing style guidelines for contributing to Besu documentation. These guidelines aim to keep the documentation consistent, well-organized, and easy to understand.
General guidelines
Be consistent - Consistency helps users follow and understand the documentation. By being consistent with your
Purpose of this document
This document contains guidelines to ensure the Besu documentation is consistent and well organised.
This is a living document and will evolve to better suit Besu users and contributors needs.
Note: Although not everything in this style guide is currently followed in the Besu documentation, these guidelines are intended to be applied when writing new content and revising existing content.
The primary audience for this document is:
- Members of the Besu team
- Developers and technical writers contributing to the Besu documentation
Mission statement
The Besu documentation contributes to a consistent and easy to understand experience for end users. We're focused on creating a great experience for both new and expert users of Ethereum clients.
General guidelines
The guiding principles for the Besu documentation are:
- Be consistent
- Keep it simple but technically correct
- Be proactive and suggest good practices
- Be informative but concise
- Be inclusive
1. Be consistent
...
word choices, visual formatting, and style of communication
...
, users know what to expect when they
...
read the documentation. For example, use consistent sentence structures when writing step-by-step instructions.
Be
...
simple but technically correct
...
- Avoid technical jargon and
...
assume the user isn’t an Ethereum expert. When an understanding of a complex Ethereum
...
concept is required, you can refer users to
...
external resources.
...
For example, to explain how the EVM works, link to
...
Simple explanations must still be technically correct.
...
a resource such as
...
the Ethereum Wiki.
Be proactive and suggest good practices
...
- Anticipate users’ needs and
...
guide them through a process. This
...
often takes the form of notes or
...
tips alongside the main explanation. Put yourself in the
...
user’s shoes and consider what questions
...
you’d have when reading the documentation
...
.
Documenting good practices is also important. For example, instruct users to secure private keys and protect RPC endpoints
...
in production environments.
...
Be informative but concise
...
- Provide enough information to help
...
users develop a
...
mental model of how
...
To provide additional detail, use sub-sections.
5. Be Inclusive
We believe that we all have a role to play to improve our world and writing inclusive doc is a first step in the right direction.
We welcome users and contributors from a wide range of of cultures, so please remember to always observe and respect their preferred language around their identity.
Avoid potential offensive terms and, for instance, prefer "allow list and deny list" to "white list and black list".
...
the software works without forcing them to read too much text or redundant detail.
...
Cut down your text by using simple words and concise sentences.
Be inclusive - ConsenSys documentation aims to be inclusive to all users. Refer to the Google inclusive documentation guide and the Microsoft bias-free communication guide
as starting points.
Writing style guide
We use ConsenSys documentation follows the Microsoft Writing Style Guide as our general guide to writing technical documentation. We take guidance from it but do not apply every rule. For example, we use title case rather than sentence case.
The Microsoft Style Guide aims for natural, simple, and clear communication.
Here are some important points we follow:
Active voice
Use active voice. Use you to create a more personal friendly style. Avoid gendered pronouns (he or she).
Contractions
Use contractions. For example, don’t.
, which is a straightforward reference for natural and clear writing style. The following are some important style recommendations:
- Abbreviations - Avoid abbreviations and acronyms unless they’re well-known or often repeated in the documentation. Use “for example” instead of “e.g,” and “that is” instead of “i.e.”
- Active voice - Use active voice where possible. Use “you” to create a personal tone.
- Code samples - Provide code samples that can be copied and pasted in a console or editor with minimal editing, and work as expected.
- When writing code samples in a programming language, refer to the programming language’s style guide.
- Always provide code samples as text in a code block; never use screenshots that would force the user to type it manually.
- When breaking up lines in a command sample, add line breaks (
\) to ensure it can work when pasted. - Don’t include the console prompt (
>,$,#,%, or the fulluser@mycomputer Develop %) or other characters that would prevent the command to run when pasted. - If values must be replaced in a sample, use placeholders such as
<your IP address>.
- Contractions - Use common contractions, such as
...
- “it’s” and
...
- “you’re,” to create a friendly, informal tone.
Recommend
...
- Sentence case for headings - Use sentence case instead of title case for headings.
- “We recommend” - In general, don’t use first person. However, use “we recommend” to introduce a product recommendation.
...
- Don’t use “ConsenSys recommends” or “it is recommended.
...
- ”
Refer to the Microsoft Guide for any other questions on style.
Documentation system guide
Refer to the Divio documentation system guide for how to structure, classify, and arrange the different functional elements of documentation (for example, tutorials, how-to guides, and references)
Example: Instead of This is not recommended for production code use We don't recommend this for production code.
Directory vs folder
Use directory over folder because we are writing for developers.
Sentence case for headings
Use sentence-style capitalization.
Assumed knowledge for readers
We have two distinct audiences to consider when developing content:
- New to Ethereum and Ethereum clients
- Experienced with Ethereum clients other than Besu
Avoid abbreviations
Try not to use abbreviations except for well known ones and some jargon. Don't use "e.g." but use "for example". Don't use "i.e." but use "that is".