Welcome to the Task Force
| Name | Interest in Task Force | |
|---|---|---|
| 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.
- Hyperledger project, most companies have a standard theme for product pages
- A badging system or checkmark for applying Standards
8 SPECIFIC RECOMMENDATIONS:
- All Hyperledger projects should utilize ReadTheDocs for documentation hosting
- 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.
Tasks to be completed
List of deliverables or work products
| Grid analysis, showing platform currently in use |
Introduction & Guiding Principles
INTRODUCTION:
Our taskforce goal is to find gaps and opportunities in existing Hyperledger Documentation. Herein, we present conclusions and determine some recommendations. This Review focuses on a comparison of a variety of documentation for the Hyperledger projects, as a case study indicative of how all documentation pages might be standardized.
This document is representative of a fact finding mission with generalized 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.
Our taskforce is mean to foster open discussion and create a place for new ideas on the betterment of Hyperledger project documentation.
GUIDING PRINCIPLES:
1. Utilize a standarLocation of Documentation: we recommend ReadtheDocs
2. Markup Language
3. Template
4. licensing
5. Weighing standardization (common template) with project uniqueness.
6 How to standardize contributions ( tutorials?)
...
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
...
| Report exists within this page. |
|
...
- Create Badging process
...
| Recommendations exist in 2 parts: our guidelines and survey results. | |
| Reflective of industry standards and existing Hyperledger Badging system. |
...
Time to complete
6 months (End 8/28/22)
...
TASK FORCE NAME: Documentation Standards
Creation Date
2/28/22
Review Material
Fabric Documentation
Comparison of Fabric Vs. Besu Documentation
Comparison of Fabric Vs. SawTooth Documentation
Comparison of Fabric Vs. Cosmos Documentation
Review of ReadtheDocs Syntax, Sphinx, and reStructured Syntax
Questionnaire For Hyperledger Documentation Survey
Fabric Documentation
Main Recommendations:
Current Status of Hyperledger Documentation Platforms
- 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
Fabric Documentation : A Documentation Pattern Template
Key Takeaways:
- 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.
- 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 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:
...
...
Fabric Vs. Besu
...
: Highlighting Layout Differences
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.
Hi team,
I'm a technical writer for ConsenSys protocols and I'd like to raise a discussion about the Besu documentation guidelines.
We recently updated and migrated all the doc guidelines across ConsenSys protocols products to this MkDocs site, which is easily readable and easy for our small team to maintain.
I'm about to update the Besu documentation guidelines for clarity and conciseness, and notice that some of the content should be exactly the same as the ConsenSys doc guide. Since the Besu guidelines already link out to some external guides (Microsoft and Google), should we link out some pages to the ConsenSys guide? The following content from the ConsenSys guide currently applies to the Besu docs:
- Configure and format Markdown
- Markdown extensions
- Documentation style guide
- Documentation release process
The ConsenSys guidelines are open source and anyone can contribute to them. Linking out to this guide would be helpful for our doc team to maintain the content in one location (and there would still be pages in the Besu doc wiki that are unique to Besu, e.g. the contribution workflow).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.
Thanks,
Alexandra Tran
...
Fabric Vs. SawTooth
...
: Stark Differences in Content & Context
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)
...
Fabric Vs. Cosmos
...
: Design Decisions for Web3
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.
...
Current Toolkit: 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.
...
Sphinx allows for customization of themes, they can be found here. Should they be standard for all projects?
Proof of Concept for
...
ReadtheDocs:
A POC was performed for ReadtheDocs using the tutorial found here. 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:
...
Image: pull requests sync easily to the Sphinx platform.
POC
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).
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.
Create Standards / Best Practices for the Hyperledger Community
Questionnaire For Hyperledger Documentation
What does the community think? Referring back to our guiding principle, we want to have harmonization between maintainers and style guide.
Quote from Community Member: (paraphrased)
I understand that our Hyperledger Project is separate from our company and it may require a complete isolation of content, and the style/markdown guidelines may need to diverge from our Company's Corporate documentation standards in the future. Our team is happy to continue this discussion here and at the next community call.
(quote refactored for generalization)
Questionnaire For Hyperledger Documentation Survey
Given that there may be uniqueness between each page, we decided to have a questionnaire. This questionnaire is meant to promote discussion regarding layout, accessibility, features and use-cases around Hyperledger documentation.
Questionnaire: Hyperledger project documentation
What features are most relevant to your project documentation page?
- Quick Start / Example Projects
- Key product features and functionality
- The ability for the user to spin up an instance
- All of the above
...
- Simple, plain visual layout
- A current / modern look and feel
- Visually stunning layout with more color options
- Visual Layout is not relevant to my documentation page
Are there any features you would like to add to your project documentation page?
- Buttons to allow for ease of use
- Tables, graphs, charts or explanatory design documents
- Styling, aesthetic or layout features
- Social Media links / Hyperledger community links
- None of the above
- All of the above
How important are unique style elements to your project for documentation usage?
- Uniqueness is very important for product adoption
- Medium amount of importance
- Not very important, end users don't need unique style for documentation usage
Are there any features you would like to remove from your project documentation page?
- Yes, I would remove some features
- No, the documentation has no extraneous data
What content do you think is most important on a documentation page?
- Introduction to the actual product itself
- A Quick Start / Example Project
- Key Concepts (section / paragraph style explanations)
- Glossary of Key Terms
- Code Snippets / Code Examples
- All of the above
Where you like your project documentation to be stored?
- Readthedocs (current platform)
- Another documentation platform
- I don’t have a preference
What layout do you prefer for your documentation landing page?
- Small concepts that link to details
- Many concepts that comprehensively reflect the project
- No preference as to layout
From an end-user experience, do you think your page is visited by mostly one or more of the following?
- Business-facing users / General purpose users
- Developers / Technical Users
How much customization do you prefer for your documentation?
- Plain, not much customization
- A bit, but generic themes are ok
- I want in depth personalization and customization
How important are charts, graphs, and other visual documentation components?
- Very important for product adoption
- Medium amount of importance
- Not very important
Does your documentation page include Provide alt text or descriptions for non-text content (images)?
...
Key Takeaways:
- The survey should give us a good idea of what Hyperledger community members value in documentation
- We hope to gain a general sense of the divergence between uniqueness and standardization
- The results of the survey should guide our final recommendations and badging system
- The survey should be reflective of the collaborative nature of the open-source community as opposed to purely a top-down approach
Conclusions / Next Steps:
Learning Materials Working Group call will analyze and discuss the survey results. Please join us! Our next call will be Monday Aug 8th at 12 noon EDT.
...