...
...
Welcome to the Task Force
...
| Name | Interest in Task Force |
|---|
Introduction, Principles & Recommendations
INTRODUCTION:
Our taskforce mission is to find gaps and opportunities in existing Hyperledger Documentation. Herein, we present conclusions and recommendations using examples that are indicative of how all documentation pages might be standardized.
This document is representative of a fact finding mission with generalized principles and specific conclusions. These conclusions should be discussed, edited and converted into direct action items. The purpose for this tone is to recognize that each Hyperledger project has a different team, with different maintainers who create and update documentation pages. Then, this document presents concrete examples that elucidate our principles and guidelines.
Our ultimate goal with this taskforce is to foster consistency and standardization for the betterment of the entire Hyperledger ecosystem.
8 GUIDING PRINCIPLES:
...
| Bobbi Muscara | Bobbi@LedgerAcademy.com | Coordinator |
| Elena Treshcheva | elena.treshcheva@exactpro.com; treshcheva@gmail.com | Review and Feedback on Framework |
| Anasuya Threse Innocent | binibft@biniworld.com | Updating 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
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:
- Standardization - Hyperledger Brand recognition
- Similar hosting platform for Documentation
- Leverage a common Markdown Language, theme and interface.
- A simpler design aesthetic is more desirable than a complex page given the goal of standardizing multiple pages within the Hyperledger Ecosystem.
- If an updated template is used, each project should emulate a newer, web3 aesthetic / open-source community visual layout
- While we recognize the implicit uniqueness of each Hyperledger project, most companies have a standard theme for product pages
- Standards should be reflected in a consistent manner through a A badging system or checkmark awarded for adherence to these principles
- Allow for community involvement to avoid a strictly top-down approach; instead, reflect the values of the open-source community
- for applying Standards
8 SPECIFIC RECOMMENDATIONS:
- All Hyperledger projects should utilize ReadTheDocs for documentation hosting
- Standardize documentation content & context to promote increased usage and project adoption
- Re-factor any existing inconsistencies in style, graphics, tables, and other content to maximize standardization between projects
- Current / Future Hyperledger Projects should both utilize the a standardized and agreed upon documentation pattern
- 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.
- Standardize graphics and the glossary section for better concept lookups and user experience.
- All Projects can leverage Discord: include or “pin” documentation relevant posts. (currently all are not pinned)
- Utilize a survey to reflect the voice of the various unique projects that have documentation pages in disparate themes with varying styles and layouts.
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 the Community
...
- Create Documentation Best Practice badging system.
...
List of deliverables or work products
| Grid analysis, showing platform currently in use | Survey For Maintainers and Community|
| Report exists within this page. | |
| Recommendations exist in 2 parts: our guidelines and survey results. | |
| Reflective of industry standards and existing Hyperledger Badging system. |
...
- The purpose of this section is to review the existing documentation hosting setup for multiple Hyperledger Projects.
- Key Takeaways:
- Most Projects use ReadtheDocs (detailed grid analysis found here)
- 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
- Fabric exists as a standard, the next section will review the fabric documentation pattern
...
- 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://wikilf-hyperledger.hyperledgeratlassian.orgnet/wiki/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
...
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).
...