...
Our taskforce is mean to foster open discussion and create a place for new ideas on the betterment of Hyperledger project documentation. Thus we would like to begin with seven eight guiding principles and seven eight specific recommendations that intertwine with those guidelines.
8 GUIDING PRINCIPLES:
- Standardization improves the speed and ease of adoption of multiple projects within the Hyperledger Ecosystem
- Each project should utilize a similar hosting platform for Documentation for ease of use and learnability
- Any documentation hosting platform used should leverage a common Markdown Language, theme and interface.
- Templates exist and therefore could be helpful in standardizing documentation pages.
- If an updated template is used, each project should emulate a newer, web3 aesthetic / open-source community visual layout
- 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
- Allow for community involvement to avoid a strictly top-down approach; instead, reflect the values of the open-source community
8 SPECIFIC RECOMMENDATIONS:
- All Hyperledger projects should utilize ReadTheDocs for documentation hosting
- Standardize documentation content to promote increased usage and project adoption
- Re-factor any existing inconsistencies in style, graphics, tables, bullet points, readability, links, and content usefulness for all projects
- Current / Future Hyperledger Projects should both utilize the a standardized and agreed upon documentation pattern
- The Fabric documentation pattern could serve as a template: ReadtheDocs for documentation, GitHub for all code truth, and a Hyperledger Wiki page for Community items and badging.
- Standardize graphics and the glossary section for better concept lookups and user experience.
- All Projects can leverage Discord: include or “pin” documentation relevant posts. (currently all are not pinned)
- Utilize a survey to reflect the voice of the various unique projects that have documentation pages in disparate themes with varying styles and layouts.
...