Introduction & Guiding Principles
INTRODUCTION:
Our taskforce goal is to find gaps and opportunities in existing Hyperledger Documentation. Herein, we present conclusions and determine some recommendations. This Review focuses on a comparison of a variety of documentation for the Hyperledger projects, as a case study indicative of how all documentation pages might be standardized.
...
Our taskforce is mean to foster open discussion and create a place for new ideas on the betterment of Hyperledger project documentation.
GUIDING PRINCIPLES:
- Standardization improves adoption of projects within the Hyperledger Ecosystem
- Each project should utilize a standard Location for Documentation: we recommend ReadtheDocs
- A common Markup Language and interface would increase standardization
- Templates exist for ReadtheDocs and can be used to improve the look and feel of any ReadtheDocs page
- Recognize and Resolve any tension between standardization (common template) with the implicit uniqueness of each Hyperledger project.
- Standards should be reflected in a consistent manner such as a badging system or checkmark awarded for adherence to these principles
SPECIFIC RECOMMENDATIONS:
- Current / Future Hyperledger Projects should utilize the documentation pattern found on the Fabric documentation sources.
- The Fabric documentation pattern is as follows: ReadtheDocs exists as the main source of non-code truth, GitHub for all code truth, and a Hyperledger Wiki page for Community related items and badging.
- All Projects can leverage Discord: include or “pin” documentation relevant posts. (currently all are not pinned)
- Re-factor all documentation content to adhere to an agreed upon documentation pattern.
- Standardize graphics across all documentation, especially in the ReadtheDocs.
- Harmonize the Read the Docs- especially in the glossary section for concept lookups and graphical standardization.
...