...

Team Goals:

1. Determine to scope of Documentation Standard Task Force
2. Collect information  both externally and Internally
3. Create Standards / Best Practices for Community
4. Create Documentation Best Practice badging system.
5. Internal:
   
   

   
   
   
   6/6

   
   

   Image Modified

   6/2

   
   

   Task: Check out https://docs.cosmos.network/ for a comparison

   1. Documentation Standards

   • How to
   • Tutorials
   • Concepts
   • Reference

   OTHER SIDE

   • What is Hyperledger Besu?
   • What can you do with Besu?
   • New to Ethereum?
   • What does Besu support?

   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 guidelines

     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.

     2. 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.

     3. 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.

     4. 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.

     5. 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 <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.

...