Tasks to be completed

• Determine The Current Status of all Projects/Tools/Libraries
• Examine the current process used for documentation
• Create Standards / Best Practices for Community
• Create Documentation Best Practice badging system.

List of deliverables or work products

• Survey For Maintainers and Community
• Report on Current Documentation processes used.
• Create Recommendations for community
• Create Badging process
• Create templates and guides for achieving badge.

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

To Do:

Complete survey

Alert Dev newsletter

Decide on the date to present to TSC

...

Recommendations

TASK FORCE RECOMENDATIONS:

GAPS AND OPPORTUNITIES

IDEAS:
       Scorecard: make sure each project is advancing and implemented guidelines across projects: example of scorecard https://github.com/ossf/scorecard
       Badging: one time badging with yearly review

TASKS

This Review focuses on a variety of documentation for the HyperLedger Fabric project, as a case study indicative of how other pages might be standardized. This initial commit is a fact finding mission with generalized conclusions. These conclusions should be discussed, edited and converted into direct action items. This is not an exhaustive review, but an initial fact finding summary. It is mean to foster open discussion and create a place for new ideas on the betterment of Hyperledger project documentation. 

...

Most current Fabric links point to the Read the Docs page as the source of truth. Thus it should be considered the de facto standard in a general sense. Fabric uses Read the Docs as the main source of truth for descriptions, GitHub as the source of truth for Code, and the HyperLedger Wiki page as the source of Truth for community related items. Projects should be customized as required. But some information in Fabric is spread out over multiple pages.  Thus, it would be more efficient to be grouped by audience for easier readability. For example, some details are on the wiki page that aren’t on Read the Docs- and vice versa. Use of graphics on the Read the Docs is sometimes inconsistent. The TaskForce could hone in on any existing inconsistencies in style, graphics, tables, bullet points, readability, links, and content usefulness for all projects to better serve future and current HyperLedger projects. 

Comparison of Fabric Vs. Besu Documentation

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. 

...

• Besu introduces itself as a product first, whereas Fabric introduces blockchain before a product introduction. 
• Should we standardize this? Should we introduce the product or concept? 
• Recommendation: Plenty of space in the ReadtheDocs for conceptual resources, let’s introduce the product first. (technical documentation typically assumes the developer knows the fundamentals)
• FAQ style Vs. Concept style. Besu uses FAQ, Fabric conceptual. 
• Practical Vs. Theory: Besu very quickly is practical. Fabric documentation puts you through lots of theory before set-up steps. 
• Main structure: Fabric is structured much differently from Besu. 
• Audience: Even though the Besu documentation is deep and thorough, it is noticeably simpler in structure for a first-time user. 
• Social Media: Besu main page is lacking social media links, and Fabric displays them- particularly the Discord is important for community engagement. 

Comparison of Fabric Vs. SawTooth Documentation

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

...

• No standard navigation style or layout exists between Fabric and Sawtooth. Each project has a different look and feel to their ReadtheDocs
• Layout and conceptual navigation is different between the projects: this could lead to slower development and adoption
• Both Fabric and Sawtooth emphasize concepts first, instead of a QuickStart or rapid development deployment project example
• Fabric has a much deeper conceptual dive into blockchain concepts, while Sawtooth has an initial conceptual dive. 
• Code formatting looks cleaner and more legible on Fabric Documentation. 
• Sawtooth begins with a Glossary, Fabric ends with a Glossary. (Should be consistent between the two.) 
• The Sawtooth documentation may be outdated and require an update to conform to the latest release (per Hardik) 

Comparison of Fabric Vs. Cosmos Documentation

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

...

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

Review of 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. 

...

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. 

Questionnaire For Hyperledger Documentation 

This questionnaire is meant to promote discussion regarding layout, accessibility, features and use-cases around Hyperledger documentation. 

...