Welcome to the Task Force
| Name | Interest in Task Force | |
|---|---|---|
| Bobbi Muscara | Bobbi@LedgerAcademy.com | Coordinator |
| Elena Treshcheva | elena.treshcheva@exactpro.com; treshcheva@gmail.com | Review and Feedback on Framework |
| Anasuya Threse Innocent | binibft@biniworld.com | Updating Documentation Content, Reviewing Documentation Framework |
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
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
GUIDING PRINCIPLES:
- Standardization - Hyperledger Brand recognition
- Similar hosting platform for Documentation
- Leverage
Introduction, Principles & Recommendations
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.
This document is representative of a fact finding mission with generalized conclusions. These conclusions should be discussed, edited and converted into direct action items. The purpose for this tone is to recognize that each Hyperledger project has a different team, with different maintainers who create and update documentation pages.
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 guiding principles and seven specific recommendations that intertwine with those guidelines.
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.
- Recognize and Resolve any tension between standardization (common template) with the implicit uniqueness of each Hyperledger project.
- Hyperledger project, most companies have a standard theme for product pages
- A 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
- for applying Standards
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.
Tasks to be completed
...
- Determine The Current Status of all Projects/Tools/Libraries
...
...
- Create Standards / Best Practices for the Community
...
- Create Documentation Best Practice badging system.
...
List of deliverables or work products
| Grid analysis, showing platform currently in use | Survey For Maintainers and Community|
| Report exists within this page. | |
| Recommendations exist in 2 parts: our guidelines and survey results. | |
| Reflective of industry standards and existing Hyperledger Badging system. |
...
- Cosmos has an updated / web3 look and feel to the UI.
- Landing page comparison: Cosmos provides a direct and immediate choice between conceptual and Quickstart / Developer Tutorials.
- Introduction comparison: similar themes addressed: history, backgrounder, orientation to product
- Key Concepts: both start with Key Concepts: blockchain, smart contracts, etc. Fabric is more comprehensive from a conceptual standpoint.
- Cosmos documentation assumes the audience knows blockchain basics, whereas Fabric is more newcomer friendly.
- Tutorials comparison: Fabric are built-in, while the Cosmos tutorials takes me to an entirely new page, new UI, new layout. (not user-friendly)
- Cosmos Tutorials means data is duplicated, developer has to start from scratch.
...
Current Toolkit: ReadtheDocs Syntax, Sphinx, and reStructured Syntax
This section highlights some of the syntax, capabilities and limitations of the ReadtheDocs structure. This is salient because the documentation of various Hyperledger projects relies on the ReadtheDocs platform.
...
Sphinx allows for customization of themes, they can be found here. Should they be standard for all projects?
Proof of Concept for
...
ReadtheDocs:
A POC was performed for ReadtheDocs using the tutorial found here. Was to ensure that certain features that are in the web3 community may be applicable to Hyperledger projects. It was found that features are available but ReadtheDocs relies on third-party plug ins and that deeper / more web3-style layouts would require customization work.
...
Image: pull requests sync easily to the Sphinx platform.
ReadtheDocs: Next Steps /
...
Insider Features: Custom CSS and JS
MKDocs Material Insider features: Ry Jones has updated the Hyperledger community regarding MK Insider features. This allows for further customization of your Hyperledger Projects documentation page.
...
- The survey should give us a good idea of what Hyperledger community members value in documentation
- We hope to gain a general sense of the divergence between uniqueness and standardization
- The results of the survey should guide our final recommendations and badging system
- The survey should be reflective of the collaborative nature of the open-source community as opposed to purely a top-down approach
Conclusions / Next Steps:
Learning Materials Working Group call will analyze and discuss the survey results. Please join us! Our next call will be Monday Aug 8th at 12 noon EDT.
...