Introduction

The mission of the Documentation Standards Taskforce is to establish consistent and comprehensive documentation standards for the Hyperledger Foundation open-source blockchain platforms. Our goal is to provide developers, users, and other stakeholders with high-quality technical documentation that is accurate, accessible, and easy to understand. Our end goal is to ensure that the technical documentation for the Hyperledger community is of the highest quality, making it easier for developers to build on these platforms and for users to understand and utilize them effectively.  Therefore, we aim to develop a set of standards that will be suggested to the Hyperledger projects that utilize the tools available to the community while also considering each project's unique features and characteristics. The purpose of this tone is to recognize that each Hyperledger project has a different team, with different maintainers who create and update documentation pages. Our task force will evaluate the current documentation environment and work collaboratively to establish standards and training materials and make the community aware of available resources. 

Tasks to be Completed

List of deliverables or work products

•  Common styling guide
•  Recommended common publishing platform
•  Document best practices for creating documentation, including information on tooling and the audiences
•  Create a template repo that new projects can use for creating their documentation

Time to complete

3-4 Months

Leader

Bobbi Muscara

Initial participant list

• Venkatraman Ramakrishna (Rama)
• Tracy Kuhrt
• John Carpenter
• Hardik Gupta
• Ben Weymouth

Meetings:

Mondays 12pm EST ( See calendar link)

Chat Channel

https://discord.com/channels/905194001349627914/1070733392020246620

References

Survey : https://docs.google.com/forms/d/1wWGjjOTh4E0BuI7sLjTtXOK_40Q63CWDQk7lsMTbSoM/edit

Paid Tooling Policy

CII Best Practices

Current Environment 

Survey Results:

https://docs.google.com/forms/d/1wWGjjOTh4E0BuI7sLjTtXOK_40Q63CWDQk7lsMTbSoM/edit#responses

Discovery of Publishing Platforms

Current Status of Hyperledger Documentation Platforms

• Key Takeaways: 
  • Most Projects use ReadtheDocs 
  • Most of those ReadtheDocs projects use either Sphinx, Restructured Text for markdown or a theme enhancer like MKdocs
  • A few projects use a non-traditional documentation hosting service, or do not use any documentation hosting service. 

Best Practices for creating Documentation

Available Community Resources: Hyperledger provides a number of paid developer tools and services for projects:

Technical Documentation:  use markdown, GitHub pages, and Material for MkDocs.

Informal documentation and details (e.g. meeting notes, meeting agendas, long-term planning documentation, etc.):  use the wiki (i.e. Confluence).

Develop:

General intro

App dev guide

System guide 

Quick Start information

1. How to
2. Tutorials
3. Concepts
4. Reference

Target Audience

Maintainers
Developers

• 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 

Badging System for Technical Documentation

On-the-fly Style Guide for Hyperledger Publications.

Documentation

• The project basic documentation :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. 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 

• 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)

Evaluation and Ideas

1. Standardize graphics and the glossary section for better concept lookups and user experience. 
2. Standardized common blockchain primer