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 projectsproject documentation.
Some Key Conclusions: Links point to the Read the Docs page as the source of truth. But some information is spread out over multiple pages, 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.
Main Recommendations:
- Projects can utilize the documentation pattern found on the Fabric sites.
- Leverage The Fabric documentation pattern is as follows: Read the Docs exists as the main source of non-code truth, Github for all code truth, and Hyperledger Wiki for Community related items and badging.
- Leverage Discord: include or “pin” documentation relevant posts. (currently all are not pinned)
- Use 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.
- Re-factor content to the various sources of truth is the main recommendation.
- Standardize graphics across all documentation, especially Read the Docs.
- Harmonize the Read the Docs- especially in the glossary section for concept lookups and graphical standarization.
- Graphics are present in the docs, but not present in the glossary- would be a “nice to have” to complete the glossary section.
...
- 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 Discord Fabric Documentation Channel: https://discord.com/channels/905194001349627914/945038395825070141
- 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
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. 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.