Team Members
Name | Role | Task | |
---|---|---|---|
Bobbi Muscara | bobbi@ledgeracademy.com | Task Force Director | Organize Group |
John Carpenter | john@globalblockchainsummit.com | Task Force Member | Organize and Help Create Documentation Standards |
Sara Moix | saraisabelmoix@gmail.com | Task Force Member | Help Organize and Support |
Benjamin Weymouth | benjamin.weymouth@gmail.com | Task Force Member | Help Organize and Support |
Team Goals:
- Determine to scope of Documentation Standard Task Force
- Collect information both externally and Internally
- Create Standards / Best Practices for Community
- Create Documentation Best Practice badging system.
- Internal:
Documentation
- The project MUST provide basic documentation for the software produced by the project. (N/A allowed.) (Justification required for "N/A".) [documentation_basics]
Details:This documentation must be in some media (such as text or video) that includes: how to install it, how to start it, how to use it (possibly with a tutorial using examples), and how to use it securely (e.g., what to do and what not to do) if that is an appropriate topic for the software. The security documentation need not be long. The project MAY use hypertext links to non-project material as documentation. If the project does not produce software, choose "not applicable" (N/A).Rationale:Potential users need documentation so that they can learn how to use the software. This documentation could be provided via the project website or repository, or even via hyperlink to some external information, so we do not specify exactly where this information is.
- The project MUST provide reference documentation that describes the external interface (both input and output) of the software produced by the project. (N/A allowed.) (Justification required for "N/A".) [documentation_interface]
Details:The documentation of an external interface explains to an end-user or developer how to use it. This would include its application program interface (API) if the software has one. If it is a library, document the major classes/types and methods/functions that can be called. If it is a web application, define its URL interface (often its REST interface). If it is a command-line interface, document the parameters and options it supports. In many cases it's best if most of this documentation is automatically generated, so that this documentation stays synchronized with the software as it changes, but this isn't required. The project MAY use hypertext links to non-project material as documentation. Documentation MAY be automatically generated (where practical this is often the best way to do so). Documentation of a REST interface may be generated using Swagger/OpenAPI. Code interface documentation MAY be generated using tools such as JSDoc (JavaScript), ESDoc (JavaScript), pydoc (Python), devtools (R), pkgdown (R), and Doxygen (many). Merely having comments in implementation code is not sufficient to satisfy this criterion; there needs to be an easy way to see the information without reading through all the source code. If the project does not produce software, choose "not applicable" (N/A).
Other
- The project MUST provide basic documentation for the software produced by the project. (N/A allowed.) (Justification required for "N/A".) [documentation_basics]
External
Articles
https://blog.prototypr.io/software-documentation-types-and-best-practices-1726ca595c7f
https://document360.com/blog/software-documentation/
https://ifs.host.cs.st-andrews.ac.uk/Books/SE9/Web/QualityMan/docstandards.html
Internal
From Fabric:
Documentation
Documentation release process
From Besu
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
Consistency is important to help our end users build a mental model of how Besu works. By being consistent with our word choices, visual formatting, and style of communication it helps users know what to expect when they refer to or search Besu documentation.
2. Keep it simple but technically correct
Avoid technical jargon and always assume our end users may not be Ethereum experts.
This doesn't mean explaining all Ethereum concepts in our documentation. Explain Besu functionality and when an understanding of complex Ethereum concepts is required refer users to relevant resources.
For example, to explain how the EVM works, link to ethdocs.org documentation such as https://github.com/ethereum/wiki/wiki/Ethereum-Virtual-Machine-(EVM)-Awesome-List
Simple explanations must still be technically correct.
3. Be proactive and suggest good practices
Being proactive means anticipating user needs and guiding them through a process. This most often takes the form of notes or tip messages alongside the main explanation. Put yourself in the user's shoes and consider what questions you would have when reading the documentation.
Do not assume required steps are implied. Err on the side of including them if you are unsure.
Documenting good practices is also important. For example, instruct users to secure private keys and protect RPC endpoints a production environments.
4. Be informative but concise
We seek a balance between providing enough relevant information to help our users develop a solid mental model of how Besu works without forcing them to read too much text or redundant detail.
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".
We suggest to refer to Google inclusive doc writing guide and Microsoft bias free writing guidelines as starting points.
Writing style guide
We use the Microsoft 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.
Use common contractions, such as it’s and you’re, to create a friendly, informal tone.
Recommend
It's acceptable to use "we recommend" to introduce a product recommendation. Don't use "Hyperledger recommends" or "it is recommended."
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".