Documentation style guide - Besu - LF Decentralized Trust Atlassian uses cookies to improve your browsing experience, perform analytics and research, and conduct advertising. Accept all cookies to indicate that you agree to our use of cookies on your device. Atlassian cookies and tracking notice, (opens new window) PreferencesOnly necessaryAccept all LF Decentralized Trust LF Decentralized Trust Spaces Apps Templates Create Besu All content Shortcuts Meetings Meetings  This trigger is hidden How-to articles How-to articles  This trigger is hidden Content Results will update as you type. Code of Conduct Contributing Developing and Conventions Documentation Documentation contribution workflow Documentation contribution guidelines Versioned documentation Documentation archive Documentation release process Documentation style guide Future Release Dates MkDocs and Markdown guide Proposal - Besu maintainers become docs maintainers Raise issues Community Governance Programs & Grants Meetings Design Documents Security Audits Start Here Performance & Stability How-to articles Incident Reports Besu Roadmap & Planning How to Contribute You‘re viewing this with anonymous access, so some content might be blocked. Close Besu / Documentation style guide More actions Documentation style guide Felipe Faraggi alexandra.tran Sally MacFarlane Nicolas Massart Owned by Felipe Faraggi Last updated: Apr 08, 2022 by alexandra.tran 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 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 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 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 ConsenSys documentation follows the Microsoft Writing Style Guide, 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 full user@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 . Contractions - Use common contractions, such as “it’s� and “you’re,� to create a friendly, informal tone. 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). , multiple selections available, Related content More info Collapse Documentation Documentation Besu More like this Documentation contribution guidelines Documentation contribution guidelines Besu More like this Suggest documentation enhancements Suggest documentation enhancements Besu More like this Hyperledger Documentation Standards Hyperledger Documentation Standards Hyperledger Mentorship Program More like this Documentation contribution workflow Documentation contribution workflow Besu More like this Besu CLI Style Guide Besu CLI Style Guide Besu More like this {"serverDuration": 14, "requestCorrelationId": "50ab33021181492fa6ce950c04951c85"}