Style guide

Style guidelines help keep the Consensys documentation consistent, concise, and readable. Refer to the following guides when writing, editing, or reviewing doc content:

• Microsoft Writing Style Guide - Refer to this guide for style, voice, grammar, and text formatting guidelines.
• Diátaxis framework - Refer to this guide for information about function-based docs.
• Consensys Editorial Style Guide
  • Refer to this guide for spelling and usage of blockchain-related terms. This guide is only available to internal Consensys contributors.

The following section also highlights the top five style tips from these guides.

Top five style tips

1. Organize content by function

Write and organize docs based on function:

• How-to guides provide instructions to achieve a specific outcome. How-to guides assume users already have some basic knowledge or understanding of the product.
• Conceptual content, or explanation, provides background information about a feature. Conceptual content can explain what the feature is, how it works at a high level, why it's needed, and when and where it's used.
• Tutorials provide a set of end-to-end steps to complete a project. Tutorials are complete and reproducible. They don't assume users have prior knowledge of the subject or required tools.
• Reference content provides technical descriptions of APIs, command line options, and other elements of code. Reference content is straightforward and doesn't include long explanations or guides.

2. Use a conversational tone

Be simple and conversational in your writing:

• In general, use active voice, present tense, and second person to focus on the reader.
• Use common contractions, such as "it’s" and "you’re," as if you're speaking to the reader.
• Be informal, but not too informal. Don't use slang, figures of speech, or run-on sentences.

example

❌ If we are unable to find another library that works with the execution environment, another way of solving the problem is by patching the dependency ourselves. For this, patch-package can be leveraged.

✅ If you can't find another library that works with the execution environment, you can patch the dependency yourself using patch-package.

3. Write for developers

Write for a developer audience:

• You don't need to market the product to the reader. Understand what they're seeking to learn or do, and optimize your content to help them achieve that quickly.
• List prerequisites and suggest good practices. For example, instruct readers to secure private keys and protect RPC endpoints in production environments.
• Write code samples that are readable, can be easily copied and pasted, and work as expected.

example

❌ To start Teku, run the following command:

// Set --ee-endpoint to the URL of your execution engine and
// --ee-jwt-secret-file to the path to your JWT secret file.
teku \
  --ee-endpoint=http://localhost:8550 \
  --ee-jwt-secret-file=my-jwt-secret.hex \
  --metrics-enabled=true \
  --rest-api-enabled=true

✅ To start Teku, run the following command:

teku \
  --ee-endpoint=<URL of execution engine>        \
  --ee-jwt-secret-file=<path to JWT secret file> \
  --metrics-enabled=true                         \
  --rest-api-enabled=true

4. Create scannable content

Make sure readers can effectively scan your content:

• Get to your point fast and make your point clear.
• Use short, simple sentences. Remove nonessential, redundant, or non-specific words and sentences.
• Break up three or more paragraphs of text with subheadings, admonitions, lists, tables, code samples, or images.
• Establish patterns in content. Use consistent language across list items and page titles. Use consistent content structure across different pages.

example

❌ Cryptographic techniques must be leveraged by the private transaction manager in order to achieve transaction authenticity, participant authentication, and historical data preservation (that is, through a chain of cryptographically hashed data). Much of the cryptographic work including symmetric key generation and data encryption/decryption is delegated to the enclave instead of the private transaction manager in order to achieve a separation of concerns, as well as to provide performance improvements through parallelization of certain crypto-operations.

✅ The private transaction manager must use cryptographic techniques to:

• Authenticate transactions.
• Authenticate participants.
• Preserve historical data.

It delegates this work to the enclave, which manages encryption and decryption in isolation. The separation of duties between the private transaction manager and enclave improves performance and strengthens the security of private keys.

5. Format text properly

Follow these rules for formatting common text elements:

• Use sentence case for headings, titles, and labels.
• Use code formatting (surround text with backticks `) for references to URLs and file names.
• Use bold text (surround text with double asterisks **) for references to user interface elements.
• Use descriptive link text.

example

❌ Click here for Besu support.

✅ If you have questions about Besu for public networks, ask on the besu channel on Hyperledger Discord.