Team Members
Name | Role | Task | |
---|---|---|---|
Bobbi Muscara | bobbi@ledgeracademy.com | Task Force Director | Organize Group |
John Carpenter | john@globalblockchainsummit.com | Task Force Member | Organize and Help Create Documentation Standards |
Sara Moix | saraisabelmoix@gmail.com | Task Force Member | Help Organize and Support |
Benjamin Weymouth | benjamin.weymouth@gmail.com | Task Force Member | Help Organize and Support |
...
Determine The Current Status of all Projects/Tools/Libraries
...
- The purpose of this section is to review the existing documentation hosting setup for multiple Hyperledger Projects.
- Key Takeaways:
- Most Projects use ReadtheDocs
- Most of those ReadtheDocs projects use either Sphinx, Restructured Text for markdown or a theme enhancer like MKdocs
- A few projects use a non-traditional documentation hosting service, or do not use any documentation hosting service.
- Might be prudent to standardize / harmonize the documentation since most projects utilize ReadtheDocs
Project | Documentation | File Type / Documentation Service | Notes | Location | Wiki Page Categories | Repos | |
---|---|---|---|---|---|---|---|
Fabric | READTHEDOCS | .RST FILE and .MD FILES | Built with Sphinx using a theme provided by Read the Docs. | https://hyperledger-fabric.readthedocs.io/en/latest/ | Documentation & Resources
| Repository | |
Besu | READTHEDOCS | .MKDOC ( Material design) and .MD files | Hyperledger Besu and its documentation are licensed under Apache 2.0 license / This Readthedocs.org documentation is maintained with love by Hyperledger Besu community. Made with Material for MkDocs | https://besu.hyperledger.org/en/stable/ | DocumentationDocumentation on Hyperledger Besu can be found here: https://besu.hyperledger.org/ | Repositories | |
Sawtooth | READTHEDOCS | .RST FILE and .MD FILES | Sawtooth 1.2 documentation has not yet been completely converted to the new site’s format. You can find the documentation in sphinx-doc rst format at: | https://sawtooth.hyperledger.org/docs/1.2/ | Documentation | Repositories | |
Iroha | READTHEDOCS | .RST FILE and .MD FILES | Built with Sphinx using a theme provided by Read the Docs. | https://iroha.readthedocs.io/en/develop/ | Documentation | Repositories | |
Indy | READTHEDOCS | .RST FILE and .MD FILES | Built with Sphinx using a theme provided by Read the Docs. | https://indy.readthedocs.io/en/latest/ | Documentation
|
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
Team Members
...
Determine The Current Status of all Projects/Tools/Libraries
- Matrix Sphinx is a tool that allows us to create documentation using simple markup languages and generate multiple output formats: HTML, LaTeX, PDF, Confluence, ePub, and plain text.
- https://developers.google.com/season-of-docs
https://readthedocs.org/
Project | Documentation | Type | Notes | Location | Wiki Page Categories | Repos | Fabric | READTHEDOCS | .RST FILE | Built with Sphinx using a theme provided by Read the Docs. | https://hyperledger-fabric.readthedocs.io/en/latest/ | Resources
| Repository | Besu | READTHEDOCS | .MKDOC ( Material design) | Hyperledger Besu and its documentation are licensed under Apache 2.0 license / This Readthedocs.org documentation is maintained with love by Hyperledger Besu community. Made with Material for MkDocs | https://besu.hyperledger.org/en/stable/ | DocumentationDocumentation on Hyperledger Besu can be found here: https://besu.hyperledger.org/ | Repositories | Sawtooth | READTHEDOCS | https://github.com/hyperledger/sawtooth-core | Sawtooth 1.2 documentation has not yet been completely converted to the new site’s format. You can find the documentation in sphinx-doc rst format at: | https://sawtooth.hyperledger.org/docs/1.2/ | Documentation | Repositories | Iroha | Repositories | hyperledger | iroha | Built with Sphinx using a theme provided by Read the Docs.iroha.readthedocs.io/en/develop/ | Documentation | Repositories | Indy | https://indy.readthedocs.io/en/latest/ | Documentation
| |||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Aries | READTHEDOCS | .RST FILE and .MD FILES | ReadtheDocs | Read me bring you to edx classes. | DocumentationFor those new to the Aries community, Trust over IP and verifiable credentials, Linux Foundation provides two courses about the concepts and technology:
The latter is obviously more focused on Aries, with the first chapter providing a summary of the former course, and a series of hands on labs based on Aries implementations. | RepositoriesNote that while the frameworks listed below are written in a specific, identified language, for the the business layer applications built on top of the frameworks can be implemented in any language. https://github.com/hyperledger/aries https://github.com/hyperledger/aries-rfcs https://github.com/hyperledger/aries-cloudagent-python https://github.com/hyperledger/aries-framework-dotnet https://github.com/hyperledger/aries-framework-go RepositoriesHyperledgerindynodeHyperledgerindyplenumHyperledger/indy-sdkhyperledger/aries-agent-test-harness Hyperledger/indy-agent | Aries | ©2022, xuning. | Powered by Sphinx 4.4.0 & Alabaster 0.7.12 | Page source | Read me bring you to edx classes. | DocumentationFor those new to the Aries community, Trust over IP and verifiable credentials, Linux Foundation provides two courses about the concepts and technology:
The latter is obviously more focused on Aries, with the first chapter providing a summary of the former course, and a series of hands on labs based on Aries implementations. | https://github.com/hyperledger/aries-mobile-agent-xamarin All Aries repositories - https://github.com/hyperledger?utf8=%E2%9C%93&q=aries&type=&language= | |||||||||||||||||||||||||||||
Bevel | READTHEDOCS | .RST FILE and .MD FILES | © Copyright 2021, Hyperledger Bevel.Revision Built withSphinxusing athemeprovided byRead the Docs. | https://hyperledger-bevel.readthedocs.io/en/latest/introduction.html | Documentation | Repositories
| ||||||||||||||||||||||||||||||||||
Cactus | READTHEDOCS | RST FILE and .MD FILES markdown or reStructuredText files with the standard theme. | Documentation | RepositoriesRepositoriesNote that while the frameworks listed below are written in a specific, identified language, for the the business layer applications built on top of the frameworks can be implemented in any language.https://github.com/hyperledger/arieshttps://github.com/hyperledger/aries-rfcs/cactus/blob/main/README.md | ||||||||||||||||||||||||||||||||||||
Caliper | READTHEDOCS /MKDocs | .RST FILE and .MD FILES Note: also uses yml for Mk Docs | powered by MkDocs and Material for MkDocs ="Jekyll v3.9.2" /> | https://hyperledger.github.comio/hyperledgercaliper/aries-cloudagent-python | Documentation: https://hyperledger.github.comio/caliper/ | RepositoriesSource code: hyperledger/aries-framework-dotnethttps://github.com/hyperledger/aries-framework-gocaliper Documentation: https://hyperledger.github.comio/hyperledger/aries-framework-javascriptcaliper/ | ||||||||||||||||||||||||||||||||||
Cello | READTHEDOCS | .RST FILE and .MD FILES | https://github.com/hyperledger/aries-vcx https://github.com/hyperledger/aries-agent-test-harness cello/blob/main/README.md | DocumentationLatest Docs | RepositoriesSource Code: https://github.com/hyperledger/aries-mobile-test-harness/cello/ Documentation https://github.com/hyperledger/aries-mobile-agent-react-nativecello.readthedocs.io/en/latest/ | |||||||||||||||||||||||||||||||||||
Firefly | JUSTThe Docs | com | hyperledger/aries | ** Just the Docs is different from ReadtheDocs. Might be easier to stick to one Layout. | This site uses Just the Docs, a documentation theme for Jekyll. | mobile-agent-xamarinAll Aries repositories - https://hyperledger.github.com/hyperledger?utf8=%E2%9C%93&q=aries&type=&language= | Bevel | io/firefly/ | https://hyperledger.github. | comio/ | hyperledgerfirefly/ | bevel© Copyright 2021, Hyperledger Bevel.Revision Built withSphinxusing athemeprovided byRead the Docs. | https://hyperledger-bevel.readthedocs.io/en/latest/introduction.html | Documentation | Repositories
| Repositories | ||||||||||||||||||||||||
Grid |
| ** Could be JusttheDocs, but it's unclear which documentation platform or theme they are using. We know Jekyll is used but that could be any number of Documentation hosting services. | <!-- Begin Jekyll SEO tag v2.8.0 → Jekyll v3.8.6 | The Hyperledger Grid documentation is available on the Grid website: Hyperledger Grid Documentation | Repositories | Cactus | Google Docs | Documentation | Caliper | MKDocs | powered by MkDocs and Material for MkDocs ="Jekyll v3.9.2" />hyperledger.iocaliperDocumentation: hyperledger.iocaliper RepositoriesSource code: caliperDocumentation: https | |||||||||||||||||||||||||||||
Transact | docs.rs | hyperledger. | io | caliper | Cello | Google Docs** Uses a different service: Docs.rs, the documentation hosting service | githubcomhyperledger/cello/blob/main/README.md | DocumentationLatest Docs | Firefly | JUSTThe Docs | https://just-the-docs.github.io/just-the-docs/ | DocumentationThe Hyperledger Transact API documentation is available on crates.io (click "Documentation"): https://crates.io/crates/transact | RepositoriesThis site uses Just the Docs, a documentation theme for Jekyll.hyperledger.iofireflyt hyperledger.iofirefly.Repositories | |||||||||||||||||||||||||||
Ursa | docs.rs | https://github.com/hyperledger/ursa-docs **Unclear: the documentation is on the github and on Docs.rs | Grid | https://grid.hyperledger.org/docs/0.3/ | <!-- Begin Jekyll SEO tag v2.8.0 → Jekyll v3.8.6 | The Hyperledger Grid documentation is available on the Grid website: Hyperledger Grid Documentation | https://rust-lang.github.comio/hyperledgermdBook/grid-website | Transact | docs.rs | http://github.com/hyperledger/transact | DocumentationThe Hyperledger Transact API documentation is available on crates.io (click "Documentation"): https://crates.io/crates/transact | Repositories | Ursa | mdBook | https://github.com/hyperledger/ursa-docs | https://rust-lang.github.io/mdBook/ | Documentation | Repositories |
Examine the current process used for documentation
It's logical to dive deeper into some case studies reflecting the above documentation grid. This section dives into Hyperledger Fabric, Sawtooth, Besu
This current process 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.
Main 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 the various sources of truth in the Fabric 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.
- Graphics are present in the Read the Docs page, but not present in the glossary- would be a “nice to have” to complete the glossary section.
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:
- HyperLedger Fabric Read the Docs: https://hyperledger-fabric.readthedocs.io/
- Designed for Multiple Audiences: Developers and Business Professionals
- Generally follows topical organization with bullet points
- Has code, helpful imagery, written explanations
- Sorts concepts into tutorials, very comprehensive spread of information
- Doesn’t include source code files, at times will link to GitHub files for more detail
- Some areas are informative, rich knowledge base
- Use Cases area could be more informative (Recommend re-fresh / re-formatting of both pages, especially wiki page. currently just links to hyperledger wiki)
- HyperLedger Fabric Main GitHub page: https://github.com/hyperledger/fabric
- Designed for developers: whether smart contract, application or enterprise blockchain developers
- Has a Readme file for general information, versioning, installation
- Links back to the HyperLedger Fabric Wiki
- HyperLedger Fabric Wiki: https://wiki.hyperledger.org/display/fabric
- Designed for general audiences, but it very brief from a descriptive standpoint.
- Is a great starting point for both technical and non technical audiences
- Includes LifeCycle badging system- noted as “Graduated” See Project LifeCycle
- Has CII Badge and Description
- Includes multiple links including the ReadtheDocs, GitHub and Original Design Documentation
- Indicates that the main documentation is the Read the Docs page
- HyperLedger Fabric Discord Documentation Channel: https://discord.com/channels/905194001349627914/945038395825070141
- The Discord channel is designed for asking and answering questions, fostering discussion regarding HyperLedger Fabric Documentation
- Not a single source of truth for any audience, however helpful for business, developer or community members
- Lots of useful links, but nothing is pinned for quick access
- As Discord becomes bigger, “pinning” will be eminently helpful
- HyperLedger Fabric LandScape Page: https://landscape.hyperledger.org/projects?selected=hyperledger-fabric
- The LandScape Page holds notable metrics, badging, links and an aggregate of the Fabric Twitter Page
- Metrics include the programming languages used, and the number of recent commits.
- The links include a comprehensive list of the various Fabric GitHub repositories
- The Twitter aggregate section includes the latest 3 tweets from the Hyperledger Foundation
Some Key Conclusions:
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.
Key Takeaways:
- 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.
...
Documentation | Repositories | ||||||
Examine the current process used for documentation
It's logical to dive deeper into some case studies reflecting the above documentation grid. This section dives into Hyperledger Fabric, Sawtooth, Besu- and looks for elements to highlight with each comparison.
This current process review
- Configure and format Markdown
- Markdown extensions
- Documentation style guide
- Documentation release process
...
Comparison of Fabric Vs. SawTooth Documentation
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:
- 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.
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:
- 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.
ReadtheDocs Highlights:
- Hyperledger documentation on ReadtheDocs is populated by files from the various Hyperledger project GitHub pages
- Those GitHub pages are synced with the ReadtheDocs platform and Pull Requests sync up to an index.rst file
- The index.rst file, as the extension might imply, is built upon Sphinx and reStructured syntax. (RST stands for reStructured)
- Sphinx and reStructured have their own syntax, formatting and are designed specifically for formatting documentation
ReStructured Text:
- reStructured is not a full fledged markdown language, but does allow for some customization
- Myriad options for text formatting is available
- images and images with hyperlinks are available
- various themes are available
- backgrounds for code snippets like dark mode are available
- Tables, References / Bibliographic citations and a Table of Contents are available
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 ReadMe:
A POC was performed for ReadtheDocs using the tutorial found here. All the templates don't show the full power of RST Syntax, while this POC shows buttons and styling that is possible. The POC 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.
POC Key Takeaways:
A Proof of Concept / Tutorial Page to dive into the customization options and reStructured Syntax for a ReadTheDocs page.
- A GitHub Repo was created for a POC of ReadtheDocs functionality
- Linked up Github with ReadtheDocs so that a Pull Request syncs to the documentation page
- ReStructured Text Syntax was utilized to test image-based button linking
Image: pull requests sync easily to the Sphinx platform.
POC Next Steps / Future Work: Custom CSS and JS
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.
This Review focuses on a variety of documentation for the HyperLedger Fabric project, as a case study indicative of the successes and pitfalls to learn 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.
...
- Current / Future Hyperledger Projects should utilize the a standard documentation pattern found on the Fabric documentation sourcesto be agreed upon.
- 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 the various sources of truth in the Fabric 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.
- Graphics are present in the Read the Docs page, but not present in the glossary- would be a “nice to have” to complete the glossary section.
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:
- HyperLedger Fabric Read the Docs: https://hyperledger-fabric.readthedocs.io/
- Designed for Multiple Audiences: Developers and Business Professionals
- Generally follows topical organization with bullet points
- Has code, helpful imagery, written explanations
- Sorts concepts into tutorials, very comprehensive spread of information
- Doesn’t include source code files, at times will link to GitHub files for more detail
- Some areas are informative, rich knowledge base
- Use Cases area could be more informative (Recommend re-fresh / re-formatting of both pages, especially wiki page. currently just links to hyperledger wiki)
- HyperLedger Fabric Main GitHub page: https://github.com/hyperledger/fabric
- Designed for developers: whether smart contract, application or enterprise blockchain developers
- Has a Readme file for general information, versioning, installation
- Links back to the HyperLedger Fabric Wiki
- HyperLedger Fabric Wiki: https://wiki.hyperledger.org/display/fabric
- Designed for general audiences, but it very brief from a descriptive standpoint.
- Is a great starting point for both technical and non technical audiences
- Includes LifeCycle badging system- noted as “Graduated” See Project LifeCycle
- Has CII Badge and Description
- Includes multiple links including the ReadtheDocs, GitHub and Original Design Documentation
- Indicates that the main documentation is the Read the Docs page
- HyperLedger Fabric Discord Documentation Channel: https://discord.com/channels/905194001349627914/945038395825070141
- The Discord channel is designed for asking and answering questions, fostering discussion regarding HyperLedger Fabric Documentation
- Not a single source of truth for any audience, however helpful for business, developer or community members
- Lots of useful links, but nothing is pinned for quick access
- As Discord becomes bigger, “pinning” will be eminently helpful
- HyperLedger Fabric LandScape Page: https://landscape.hyperledger.org/projects?selected=hyperledger-fabric
- The LandScape Page holds notable metrics, badging, links and an aggregate of the Fabric Twitter Page
- Metrics include the programming languages used, and the number of recent commits.
- The links include a comprehensive list of the various Fabric GitHub repositories
- The Twitter aggregate section includes the latest 3 tweets from the Hyperledger Foundation
Some Key Conclusions:
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.
Key Takeaways:
- 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.
...
- -factor all documentation content to adhere to the various sources of truth in the 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.
- Graphics are present in the Read the Docs page, but not present in the glossary- would be a “nice to have” to complete the glossary section.
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:
- HyperLedger Fabric Read the Docs: https://hyperledger-fabric.readthedocs.io/
- Designed for Multiple Audiences: Developers and Business Professionals
- Generally follows topical organization with bullet points
- Has code, helpful imagery, written explanations
- Sorts concepts into tutorials, very comprehensive spread of information
- Doesn’t include source code files, at times will link to GitHub files for more detail
- Some areas are informative, rich knowledge base
- Use Cases area could be more informative (Recommend re-fresh / re-formatting of both pages, especially wiki page. currently just links to hyperledger wiki)
- HyperLedger Fabric Main GitHub page: https://github.com/hyperledger/fabric
- Designed for developers: whether smart contract, application or enterprise blockchain developers
- Has a Readme file for general information, versioning, installation
- Links back to the HyperLedger Fabric Wiki
- HyperLedger Fabric Wiki: https://wiki.hyperledger.org/display/fabric
- Designed for general audiences, but it very brief from a descriptive standpoint.
- Is a great starting point for both technical and non technical audiences
- Includes LifeCycle badging system- noted as “Graduated” See Project LifeCycle
- Has CII Badge and Description
- Includes multiple links including the ReadtheDocs, GitHub and Original Design Documentation
- Indicates that the main documentation is the Read the Docs page
- HyperLedger Fabric Discord Documentation Channel: https://discord.com/channels/905194001349627914/945038395825070141
- The Discord channel is designed for asking and answering questions, fostering discussion regarding HyperLedger Fabric Documentation
- Not a single source of truth for any audience, however helpful for business, developer or community members
- Lots of useful links, but nothing is pinned for quick access
- As Discord becomes bigger, “pinning” will be eminently helpful
- HyperLedger Fabric LandScape Page: https://landscape.hyperledger.org/projects?selected=hyperledger-fabric
- The LandScape Page holds notable metrics, badging, links and an aggregate of the Fabric Twitter Page
- Metrics include the programming languages used, and the number of recent commits.
- The links include a comprehensive list of the various Fabric GitHub repositories
- The Twitter aggregate section includes the latest 3 tweets from the Hyperledger Foundation
Some Key Conclusions:
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.
Key Takeaways:
- 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.
- Configure and format Markdown
- Markdown extensions
- Documentation style guide
- Documentation release process
...
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
...
Since many Hyperledger projects use ReadtheDocs, it is important to have an understanding of the underlying structure of the platform. Thus, this
...
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. documentation hosting system. structure.
ReadtheDocs Highlights:
- Hyperledger documentation on ReadtheDocs is populated by files from the various Hyperledger project GitHub pages
- Those GitHub pages are synced with the ReadtheDocs platform and Pull Requests sync up to an index.rst file
- The index.rst file, as the extension might imply, is built upon Sphinx and reStructured syntax. (RST stands for reStructured)
- Sphinx and reStructured have their own syntax, formatting and are designed specifically for formatting documentation
- Matrix Sphinx is a tool that allows us to create documentation using simple markup languages and generate multiple output formats: HTML, LaTeX, PDF, Confluence, ePub, and plain text.
ReStructured Text:
- reStructured is not a full fledged markdown language, but does allow for some customization
- Myriad options for text formatting is available
- images and images with hyperlinks are available
- various themes are available
- backgrounds for code snippets like dark mode are available
- Tables, References / Bibliographic citations and a Table of Contents are available
...
Proof of Concept for ReadMe:
A POC was performed for ReadtheDocs using the tutorial found here. Was A POC was performed for ReadtheDocs using the tutorial found here. All the templates don't show the full power of RST Syntax, while this POC shows buttons and styling that is possible. The POC 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.
POC Key Takeaways:
...
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. 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 Community
What does the community think? Harmonization between maintainers and style guide.
Quote from Community Member:
On the other hand, I understand that Besu is separate from ConsenSys and it may require a complete isolation of content, and the style/markdown guidelines may need to diverge from ConsenSys's in the future. Our team is happy to continue this discussion here and at the next community call.
Survey For Maintainers and Community Community
Consistency between These points: Survey:
1. Location of Documentation: we recommend ReadtheDocs
2. Markup Language
3. Template
...
Create Documentation Best Practice badging system.
Internal:
6/6
6/2
Task: Check out https://docs.cosmos.network/ for a comparison
...