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 |
https://developers.google.com/season-of-docs | |||
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:
6/66/2
Task: Check out https://docs.cosmos.network/ for a comparison
Documentation Standards
OTHER SIDE
Suggestion:
Create a Technology overview for all products
Get 4 or five bullet point references consistent for all project
Task: Create a Matrix for badging documentation effort of projects:
OpenSSF Best Practices Badge application complete with Documentation.
Different doc: Dev and User, general knowledge quick jump to spinning up the project.
Start: Glossary Gentle
Read the Doc : Conceptual. comprehensive How to move from audience members' needs?
Different sub headings for users, Sub Topic - developers only - Cosmos read docs is example
Documentation tends to cover basic information that users should or shouldn't be aware.
STANDARDIZED GLOSSARY
General intro
App dev guide
System guide
State audience
Quick Start information
Contribu6tor .md file as an initial entry point. Text or points to files on read the docs.
Project/ Badging
Github Documentation
Read the Docs
Wiki
Discord
Project/ Badging
Github Documentation
Read the Docs
Wiki
Discord
General - Product Introduction Conceptual End User Developer Fabric Sawtooth Indy Iroha Besu Firefly 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
David Boswell
Hart Montgomery Arun S M Kamlesh Nagware – Thanks for your feedback and I see that you've each mentioned that having more resources at the graduated level would be helpful. Here are some ideas to consider, although it would also be really helpful to hear from people involved in projects about what additional help they'd be interested in.
- I think there is probably something around documentation and translation support for graduated projects that would be worth doing. If possible, perhaps we can make some budget available to bring in a technical writer, for example, to help with project docs?
- We could also make the resources available to Incubation projects time bound – for instance, an Incubation project could have a year to grow and mature and at the end of that time the TSC decides to either move it to Graduated or move it to the Labs.
- The project placement on the Hyperledger site does not currently provide a distinction between Graduated and Incubation projects since they're treated the same way now. We're looking at updating the site this year to give more prominent positioning to Graduated projects, so the priority placement item will become more of an incentive.
- The same is true of Workshops – this is a new concept so we have not yet seen the benefits to a project of running a workshop. After we've done a few of these we can analyze the outcome and if we can see a bump in users and contributors to a project after a workshop then this will become an incentive for Graduation status too.
Project participation and interface:
- CONTRIBUTING.md - How to contribute to this project
- INSTALL.md - How to install/quick start
- governance.md - How the project is governed
- roadmap.md - Overall direction of the project
- background.md - Background research
- api - Application Programming Interface (API), inc. data downloads
Criteria:
- criteria.md - Criteria for "passing" badge
- other.md - Criteria for other badges (silver and gold)
Development processes and security:
- requirements.md - Requirements (what's it supposed to do?)
- design.md - Architectural design information
- implementation.md - Implementation notes
- testing.md - Information on testing
- security.md - Why it's adequately secure (assurance case)
Besu: the documentation is released when a new version of the Besu software is released.
General guidelinesBe 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 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.
- 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).
1. Manually create a release on GitHub
When a new version of the software is released, the documentation team manually creates a release on the corresponding GitHub documentation repository.
Documentation versioning follows the same Calendar Versioning (CalVer) pattern as the software to help users match the documentation version to the software version easily.
The GitHub release creation process tags the Git repository with the new version (for example,
21.1.4
).2. Automatically build the documentation on RTD
When Read the Docs (RTD) detects a new tag on a documentation repository, RTD automatically generates the following documentation versions:
- Latest - Corresponds to the latest commit in the main branch of the documentation repository.
- CalVer - Corresponds to the tag in the main branch that was created during the release (for example,
21.1.4
). - Stable - Corresponds to the last created tag.
RTD builds all three versions, all showing the same content from the same commit.
As contributors continue to work on the documentation, RTD rebuilds the latest version from the latest main commit each time a new PR is merged, and the CalVer and stable versions remain behind latest.
Note: The Besu documentation repository default branch is now named main.
3. Automatically activate the documentation version on RTD
By default, RTD doesn’t activate or publish new CalVer versions, but Besu documentation has custom rules for RTD to automatically do so. If you have access to RTD as a Besu documentation maintainer, you can view these automation rules and the history of version activations in the Admin tab of the RTD documentation project.
General:
Tablet of Contents
https://github.com/jaredweinfurtner/docs-project-layout
Developer Documentation
TBD
Technical Documentation
I have created a template/demo repository for technical documentation:
- repo: https://github.com/jaredweinfurtner/docs-project-layout
- generated documentation: https://jaredweinfurtner.github.io/docs-project-layout
For technical documentation, a user should not have to browse through the code repository on GitHub. The user should also have many options to read the technical documentation: Easily navigatable web page, PDF, ePub for eReaders, etc. The following is a proposal on how to approach technical documentation that is simple for contributors to manage the documentation and simple for readers to take in.
Sphinx
Sphinx is a tool that allows us to create documentation using simple markup languages and generate multiple output formats: HTML, LaTeX, PDF, Confluence, ePub, and plain text. It has an easy to understand hierarchical structure with automatic indices. More importantly, it has a large community building plugins & extensions.
To learn more, visit: https://www.sphinx-doc.org
Plugins/Extensions
The power of Sphinx is in its plugin support. We are currently using 4 plugins to make life easier for a contributor:
sphinx_rtd_theme
- Read the Docs (https://docs.readthedocs.io) is used quite a bit in the open-source community and providing a familiar experience using their theme with our documentation for users and contributors has obvious benefits.sphinxcontrib-drawio
- This allows direct reference of*.drawio
files directly within the documentation, so no need to export as png every time you make a simple edit eliminating the chance of out-of-sync files and images.reStructuredText:
.. drawio-figure:: my-awesome-model.drawio
Markdown:
```{drawio-figure} my-awesome-model.drawio
```
myst-parser
- By default, Sphinx uses reStructuredText (another markup language similar to Markdown). This plugin allows Markdown support within Sphinx to make it easier to those not wanting to learn another language. For more information, please see: https://myst-parser.readthedocs.iosphinxcontrib-plantuml
- similar to the drawio plugin. It allows PlantUML files to be directly referenced in the documentation.
There are so many more plugins that we can use to make our life easier since documentation is never anyone's favorite task: https://github.com/sphinx-contrib/
Docker
It is often necesseary to generate the documentation locally to verify your changes before commiting. To make life easier for a contributor, I have packaged all of the installation, plugins, and configurations in a docker image so that the same container that builds the documentation locally is the same container that the CI environment builds for deployment.
Source: https://github.com/jaredweinfurtner/sphinx-drawio-docker
Docker Hub: https://hub.docker.com/repository/docker/jaredweinfurtner/sphinx-drawio-docker
Simply run the following in the /docs
folder to generate the static html with the Read the Docs theme:
|
Structure
Inside the /docs folder, the following structure is proposed:
|
/build/**
Contains generated documentation and should be ignored via .gitignore
/build/html/**
Contains static html that can be deployed as any other static html site - for example to: Read the Docs, GitHub Pages, etc
/build/latex/**
Contains mainly cached files for quicker follow-up generation of the pdf, but your *.pdf should be buried in here somewhere
/source/index.rst|md
This is your landing page and should contain the tree structure of your documentation. I highly recommend separating each section & subsection into its own folder so that you can include any diagrams alongside the .rst file.
/source/conf.py
This is the Sphinx configuration file and is the only thing you need to copy & configure into your own project. Simply set the properties listed at the top for your particular project:
|
GitHub Pages
GitHub Pages offers static html hosting of our generated Sphinx documentation with the ReadTheDocs theme. It nicely binds the project's GitHub repo with technical documentation so the user experience is seamless. It offers automatic publishing by designating a git branch and a subfolder that contains the documentation (i.e. docs
branch with a /docs
subfolder). Normally GitHub uses Markdown to generate the documentation, but it doesn't have the capabilities of Sphinx plugin support (such as draw.io, PlantUML, PDF support).
For more information, please see: https://pages.github.com
Compatibility with Sphinx
Out-of-the-box GitHub Pages is not compatible with Sphinx structure; however, it is easily fixed. To configure GitHub pages to simply host the statically generated Sphinx documentation (instead of its own processing/theme), we simply add an empty.nojekyll
file in the /docs
folder. There's even an extension sphinx.ext.githubpages
that takes care of that automatically (example).
Build / Deployment
It is good standard practice to never check-in generated code to a git repo, so we do not check-in the generated Sphinx html from our local environments. Therefore, it is necessary to generate the documentation (static html) in a CI environment and push it to the docs
branch under the /docs
folder so that GitHub Pages can automatically deploy it.
GitHub Actions
GitHub Actions is GitHub's CI system (think Jenkins) and allows us to trigger our static html generation whenever a change is made to the master branch. We simply generate the static html via the same docker command we use locally during development, move the static html to the root /docs folder for GitHub Pages, add the .nojekyll to tell GitHub Pages to simply host our own static html.
Example GitHub Action for GitHub Pages integration (example result: https://jaredweinfurtner.github.io/docs-project-layout/):
doc-generation.yml
1 |
|
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".