|
| 1 | +--- |
| 2 | +description: Documentation style guidelines |
| 3 | +sidebar_position: 4 |
| 4 | +--- |
| 5 | + |
| 6 | +# Documentation style guide |
| 7 | + |
| 8 | +The following are writing style guidelines for contributing to the ConsenSys documentation. These guidelines aim to keep the documentation consistent, well-organized, and easy to understand. |
| 9 | + |
| 10 | +## General guidelines |
| 11 | + |
| 12 | +1. **Be consistent** - Consistency helps users follow and understand the documentation. By being consistent with your 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](https://docs.microsoft.com/en-us/style-guide/procedures-instructions/writing-step-by-step-instructions). |
| 13 | + |
| 14 | +1. **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 a resource such as the [Ethereum Wiki](<https://eth.wiki/en/concepts/evm/ethereum-virtual-machine-(evm)-awesome-list>). |
| 15 | + |
| 16 | +1. **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. |
| 17 | + |
| 18 | + Documenting good practices is also important. For example, instruct users to secure private keys and protect RPC endpoints in production environments. |
| 19 | + |
| 20 | +1. **Be informative but concise** - Provide enough information to help users develop a mental model of how 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](https://docs.microsoft.com/en-us/style-guide/word-choice/use-simple-words-concise-sentences). |
| 21 | + |
| 22 | +1. **Be inclusive** - ConsenSys documentation aims to be inclusive to all users. Refer to the [Google inclusive documentation guide](https://developers.google.com/style/inclusive-documentation) and the [Microsoft bias-free communication guide](https://docs.microsoft.com/en-us/style-guide/bias-free-communication) as starting points. |
| 23 | + |
| 24 | +## Writing style guide |
| 25 | + |
| 26 | +ConsenSys documentation follows the [Microsoft Writing Style Guide](https://docs.microsoft.com/en-us/style-guide/welcome/), which is a straightforward reference for natural and clear writing style. The following are some important style recommendations: |
| 27 | + |
| 28 | +- **Abbreviations** - Avoid [abbreviations and acronyms](https://docs.microsoft.com/en-us/style-guide/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." |
| 29 | +- **Active voice** - Use [active voice](https://docs.microsoft.com/en-us/style-guide/grammar/verbs#active-and-passive-voice) where possible. Use "you" to create a personal tone. |
| 30 | +- **Code samples** - Provide code samples that can be copied and pasted in a console or editor with minimal editing, and work as expected. |
| 31 | + - When writing code samples in a programming language, refer to the programming language's style guide. |
| 32 | + - Always provide code samples as text in a code block; never use screenshots that would force the user to type it manually. |
| 33 | + - When breaking up lines in a command sample, add line breaks (`\`) to ensure it can work when pasted. |
| 34 | + - Don't include the console prompt (`>`,`$`,`#`,`%`, or the full `user@mycomputer Develop %`) or other characters that would prevent the command to run when pasted. |
| 35 | + - If values must be replaced in a sample, use placeholders such as `<your IP address>`. |
| 36 | +- **Contractions** - Use common contractions, such as "it’s" and "you’re," to create a friendly, informal tone. |
| 37 | +- **Sentence case for headings** - Use sentence case instead of title case for headings. |
| 38 | +- **"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." |
| 39 | +- **GitHub permalinks** - When linking to a GitHub file, use the <!-- markdown-link-check-disable-next-line --> [permanent link (permalink)](https://docs.github.com/en/repositories/working-with-files/using-files/getting-permanent-links-to-files) to the file. You can copy the permalink by selecting the ellipses (`...`) in the upper right corner of the file page, and selecting **Copy permalink**. |
| 40 | + |
| 41 | +Refer to the [Microsoft Guide](https://docs.microsoft.com/en-us/style-guide/welcome/) for any other questions on style. |
| 42 | + |
| 43 | +## Documentation categories |
| 44 | + |
| 45 | +A typical documentation page falls into one of the following four categories: |
| 46 | + |
| 47 | +1. [**How to**](https://documentation.divio.com/how-to-guides/) - How-to content provides instructions to achieve a specific outcome. How-to content assumes users already have some basic knowledge or understanding of the product. |
| 48 | + |
| 49 | +1. [**Concepts**](https://documentation.divio.com/explanation/) - Conceptual content provides background information and context 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. |
| 50 | + |
| 51 | +1. [**Tutorials**](https://documentation.divio.com/tutorials/) - 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. |
| 52 | + |
| 53 | +1. [**Reference**](https://documentation.divio.com/reference/) - 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. |
| 54 | + |
| 55 | +A page in each category should link to the related pages in the other categories, if they exist. |
| 56 | + |
| 57 | +For more information about these documentation types and the differences between them, refer to the [Divio documentation system guide](https://documentation.divio.com/). |
0 commit comments