Documentation Standards Task Force
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. | 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 | 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: | Documentation | Repositories |
| |
Iroha | READTHEDOCS | .RST FILE and .MD FILES | Built with Sphinx using a theme provided by Read the Docs. | Documentation | Repositories |
| |
Indy | READTHEDOCS | .RST FILE and .MD FILES | Built with Sphinx using a theme provided by Read the Docs.
| Documentation
| Repositories |
| |
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 https://github.com/hyperledger/aries-framework-javascript https://github.com/hyperledger/aries-vcx https://github.com/hyperledger/aries-agent-test-harness https://github.com/hyperledger/aries-mobile-test-harness https://github.com/hyperledger/aries-mobile-agent-react-native 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 | Repositories |
| |
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" /> | Documentation: https://hyperledger.github.io/caliper/ | RepositoriesSource code: https://github.com/hyperledger/caliper Documentation: https://hyperledger.github.io/caliper/ |
| |
Cello | READTHEDOCS | .RST FILE and .MD FILES |
| DocumentationLatest Docs | RepositoriesSource Code: https://github.com/hyperledger/cello/ Documentation https://cello.readthedocs.io/en/latest/ |
| |
Firefly | JUSTThe Docs | https://just-the-docs.github.io/just-the-docs/
** 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. | 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 |
|
Transact | docs.rs | http://github.com/hyperledger/transact
** Uses a different service: Docs.rs, the documentation hosting service |
| DocumentationThe Hyperledger Transact API documentation is available on crates.io (click "Documentation"): https://crates.io/crates/transact | Repositories |
| |
Ursa | docs.rs | https://github.com/hyperledger/ursa-docs
**Unclear: the documentation is on the github and on Docs.rs |
| 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 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.
Main Recommendations:
Current / Future Hyperledger Projects should utilize a standard documentation pattern to 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 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://lf-hyperledger.atlassian.net/wiki/display/fabric/
Designed for general audiences, but it very brief from a descriptive standpoint.