Welcome to the Task Force


NameEmailInterest in Task Force
Bobbi MuscaraBobbi@LedgerAcademy.comCoordinator 
Elena Treshchevaelena.treshcheva@exactpro.com; treshcheva@gmail.comReview and Feedback on Framework
Anasuya Threse Innocentbinibft@biniworld.comUpdating 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






GUIDING PRINCIPLES:

  1. Standardization - Hyperledger Brand recognition
  2. Similar hosting platform for Documentation 
  3. Leverage a common Markdown Language, theme and interface. 
  4. Hyperledger project, most companies have a standard theme for product pages 
  5. A badging system or checkmark for applying Standards

8 SPECIFIC RECOMMENDATIONS: 

  1. All Hyperledger projects should utilize ReadTheDocs for documentation hosting 
  2. 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. 
  3. Standardize graphics and the glossary section for better concept lookups and user experience. 

Tasks to be completed


List of deliverables or work products

  • Analysis of Project Documentation Platforms
Grid analysis, showing platform currently in use



  • Report on Current Documentation processes used.
Report exists within this page. 
  • Create Recommendations for community
Recommendations exist in 2 parts: our guidelines and survey results. 
  • Create Badging process, templates
Reflective of industry standards and existing Hyperledger Badging system. 


Time to complete

6 months (End 8/28/22)

Leader

Ben W

Initial participant list

Ben W
Bobbi M
John C

Chat Channel

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

References

TASK FORCE NAME: Documentation Standards

Creation Date
2/28/22

Current Status of Hyperledger Documentation Platforms

Fabric Documentation : A Documentation Pattern Template

Key Takeaways: 

Hyperledger Fabric Documentation 

HyperLedger Fabric  documentation can be found in a variety of sources, depending on your use case. Here are the main documentation standards: 

  1. HyperLedger Fabric Read the Docs: https://hyperledger-fabric.readthedocs.io/
  2. HyperLedger Fabric Main GitHub page: https://github.com/hyperledger/fabric
  3. HyperLedger Fabric Wiki: https://wiki.hyperledger.org/display/fabric
  4. HyperLedger Fabric Discord Documentation Channel: https://discord.com/channels/905194001349627914/945038395825070141
  5. HyperLedger Fabric LandScape Page: https://landscape.hyperledger.org/projects?selected=hyperledger-fabric 


Fabric Vs. Besu: Highlighting Layout Differences


This comparison is an initial analysis of the level of standardization between the Hyperledger Fabric Vs. Besu ReadTheDocs. ReadtheDocs was chosen because the ReadTheDocs is main source of documentation truth, and most deep in knowledge / helpfulness. 

Key Takeaways: 

Fabric Vs. SawTooth: Stark Differences in Content & Context

This comparison is an initial analysis of the level of standardization between the Hyperledger Fabric Vs. SawTooth ReadTheDocs.  

The terminology used between the two varies: while both begin with a key concepts / key terms introduction. Fabric emphasizes the idea of a Blockchain, while Sawtooth emphasizes the idea of a distributed ledger. While every blockchain uses a distributed ledger system, not all distributed ledgers conform to the characteristics of a blockchain. Therefore greater clarity may be gained if all documentation emphasized blockchain as the standard starting point, which utilizes practices related to distributed ledgers. 

Key Takeaways: 

Fabric Vs. Cosmos: Design Decisions for Web3

This comparison is an initial analysis between the Hyperledger Fabric documentation and the Cosmos Blockchain documentation.  

Both Cosmos and Fabric begin with a key concepts / key terms introduction. Fabric emphasizes the idea of an Enterprise level Blockchain, while Cosmos emphasizes the idea of application-specific blockchains.  

Key Takeaways: 




Current Toolkit: ReadtheDocs Syntax, Sphinx, and reStructured Syntax

image2022-7-30_19-5-11.png

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. 

ReadtheDocs Highlights: 

ReStructured Text: 

What is an RST file? Here is an RST Example from Hyperledger Fabric: 


Sphinx 

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. 

image2022-7-30_19-5-11.png

POC Key Takeaways: 

A Proof of Concept / Tutorial Page to dive into the customization options and reStructured Syntax for a ReadTheDocs page.


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. 

We can change, or add a common theme to all pages. Currently some pages use standard themes (Ex: Fabric) while others use custom themes (Ex: Besu). 

Apparently, Sphinx can also support custom CSS and JS- thus further customization could be performed. However, the caveat being that this customization would need to be synced up between projects. If different projects used different layouts, functionality it defeats the purpose of standardization. 



Create Standards / Best Practices for the Hyperledger Community

What does the community think? Referring back to our guiding principle, we want to have harmonization between maintainers and style guide. 

Quote from Community Member: (paraphrased) 

I understand that our Hyperledger Project is separate from our company and it may require a complete isolation of content, and the style/markdown guidelines may need to diverge from our Company's Corporate documentation standards in the future. Our team is happy to continue this discussion here and at the next community call.

(quote refactored for generalization) 

Questionnaire For Hyperledger Documentation Survey 

Given that there may be uniqueness between each page, we decided to have a questionnaire. This questionnaire is meant to promote discussion regarding layout, accessibility, features and use-cases around Hyperledger documentation. 

Key Takeaways: 


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. 

Questionnaire URL

Results URL: