5/22/23
Agenda:
- Welcome
- Anti Trust
- Introductions
- Yash Pimple
- Akanksha Rani
- Devesh Meena
- Elena Treshcheva
- Osama Tahir
- Yash Kataria
- Arunima Chauhuri
- Pratyay Banerjee
- John Carpenter
- Bobbi Muscara
- Presentation to the Task Force
- Summary and Time Frame
Names Area Bobbi
Akanksha Rani
Introduction Elena Report on GitHub Directory update
Next StepsAkanksha Rani
Template Suggestion
Next Step
Pratyay Banerjee Best Practices Suggestion
Next StepOnboard Suggestion
Next StepEnd of Task Force Month - 4 areas of deliverables
Work on Github Repo
https://github.com/hyperledger-labs/documentation-templateTemplate / New Brand: Get link from Ben
User Docs
Work with other Task forces
- Result : Where to put information moving forward
- Summary and Time Frame
- Mentorship Program:
- Comments
5/15/23
Anti-trust Policy Notice & Code of Conduct
- Linux Foundation meetings involve participation by industry competitors, and it is the intention of the Linux Foundation to conduct all of its activities in accordance with applicable antitrust and competition laws. It is therefore extremely important that attendees adhere to meeting agendas, and be aware of, and not participate in, any activities that are prohibited under applicable US state, federal or foreign antitrust and competition laws.
- Examples of types of actions that are prohibited at Linux Foundation meetings and in connection with Linux Foundation activities are described in the Linux Foundation Antitrust Policy available at http://www.linuxfoundation.org/antitrust-policy. If you have questions about these matters, please contact your company counsel, or if you are a member of the Linux Foundation, feel free to contact Andrew Updegrove of the firm of Gesmer Updegrove LLP, which provides legal counsel to the Linux Foundation.
- Hyperledger is committed to creating a safe and welcoming community for all. For more information, please visit our Hyperledger Code of Conduct
Attendees
David Boswell dboswell@linuxfoundation.org
Bobbi Muscara bobbi@LedgerAcademy.com
Arunima Chaudhuri arunimachaudhuri2020@gmail.com
Maurice Magorane magorane@gmail.com
Akanksha Rani akankshar8800@gmail.com
Balveer Singh Rao balveer.singhrao.eee21@itbhu.ac.in
Pratyay Banerjee pratyaybanerjeex@gmail.com
Elena Treshcheva elena.treshcheva@exactpro.com
Devesh Meena nothefakedevesh@gmail.com
Ayush Kumar Singh ayushk4549@gmail.com
Aswin Shailajan aswins2108@gmail.com
Pranit Patil patilpranit3112@gmail.com
Rohit Patil rohitpatil1625@gmail.com
Yash Kataria yashkataria1993@gmail.com
Yash Pimple yashpimple22@gmail.com
doc ops
Community Documentation Needs
Task | Name | Tasks | |
---|---|---|---|
Work on Github Repo | Bobbi (bobbi@ledgeracademy.com) Akanksha Rani Arunima Chaudhuri Yash Pimple (yashpimple22@gmail.com) Balveer Singh Rao (balveer.singhrao.eee21@itbhu.ac.in Aswin Shailajan Pratyay Banerjee |
| |
Template | Yash Kataria yashkataria1993@gmail.com Akanksha Rani akankshar8800@gmail.com Arunima Chaudhuri Pratyay Banerjee |
| |
User Docs | Balveer Singh Rao Balveer Singh Rao 5-Year IDD Electrical Engineering Devesh Meena Arunima Chaudhuri Yash Pimple (yashpimple22@gmail.com) Rohit Patil (rohitpatil1625@gmail.com) Maurice Magorane magorane@gmail.com
| Determine what learners need
| |
Work with other Task forces | TOC call Thursday 5/11 10amEDT *Best Practices Task Force presentation https://github.com/hyperledger/toc/pull/111#discussion_r1191202964 |
Wiki Page
Getting Started
Website
Discord
GitHub
Personas
Tasks
Meeting Times
Report To TSC
Tasks For Mentee's
Mentee Interview
5/11/23
Bobbi - TOC meeting Best Practices mentioned the Github Contribution Guide
- Who needs it?
Where does it reside?
toc/guidelines/github-contribution-guide.md
- research the documentation piece and comment foe Dave E.
Status Update
5/8/23
Task | Name | Tasks |
---|---|---|
Work on Github Repo | Bobbi (bobbi@ledgeracademy.com) |
|
Template | Akanksha Rani Pratyay Banerjee |
|
User Docs | Determine what learners need
| |
Work with other Task forces | Akanksha Rani Pratyay Banerjee | TOC call Thursday 5/11 10amEDT *Best Practices Task Force presentation |
5/1/23
Tasks:
- Further define Mentees' deliverables
- Create a timeline for deliverables
- Support Mentee Programs with Documentation
- Presentation to new Mentees / Mentors
Deliverables
- A set of documentation guidelines and templates that can be used by all Hyperledger projects (Github / Readthe Docs)
- A style guide for Hyperledger documentation
- A list of recommended documentation tools and templates
- A plan for integrating the new guidelines and templates into existing Hyperledger projects
- A series of blog posts or tutorials on how to use the new guidelines and templates
- Best Practices Coordinators
- User Guides:
Community Contributors
Maintainers
New Coders
SIG Chairs
TOC Members
Solution Providers
4/26/23
Personas
SIG Chairs
SIG Members
TOC Members
Maintainers
Developers
Users/community members
4/17/23
List of mentee tasks.
Define Task Force and Mentee Deliverables.
Project discussion for doc needs.
Make the Docs - color scheme - from Hyperledger rebranding and any customizations should use color scheme from projects logo.
4/10/23
Task 2 | 4/13/23 | ||
---|---|---|---|
What is Task Force Deliverables and Mentee deliverables | 5/1/23 4/26/23 Expected Outcome
| ||
Determine how Mentee can assist the documentation needs of the below projects | Support Mentee Projects | ||
Recommended common publishing platform depending on user: hyperledger-labs/documentation-template: Template for creating documentation for Hyperledger projects | |||
Recommendations for Best Practice Task Force | What does that look like. | ||
Define Audience | Projects TOC SIG Chairs Meetup | ||
Recommendations | List of deliverables or work products
|
GitHub Pages (https://pages.github.com/): GitHub Pages allows you to create and host a website for your repository directly from a GitHub repository. You can use it to create user guides and documentation using Markdown files.
Read the Docs (https://readthedocs.org/): Read the Docs is a platform that automatically builds, versions, and hosts documentation for your projects. It integrates with GitHub and supports Markdown and reStructuredText formats.
GitBook (https://www.gitbook.com/): GitBook is a documentation platform that integrates with GitHub, allowing you to create user guides and documentation with a user-friendly interface. It supports Markdown and offers features like collaboration, versioning, and custom domains.
Docusaurus (https://docusaurus.io/): Docusaurus is an open-source documentation website generator that supports Markdown files. It integrates with GitHub and offers features like versioning, translations, and search functionality.
MkDocs (https://www.mkdocs.org/): MkDocs is an open-source static site generator geared towards creating project documentation. It supports Markdown files and can integrate with GitHub Pages for hosting.
Sphinx (https://www.sphinx-doc.org/): Sphinx is a documentation generator that supports reStructuredText and can create output formats like HTML, PDF, and EPUB. It integrates with GitHub and can be used with Read the Docs for hosting.
Jekyll (https://jekyllrb.com/): Jekyll is a static site generator that supports Markdown and can be used to create user guides and documentation. It integrates with GitHub Pages for easy hosting.
VuePress (https://vuepress.vuejs.org/): VuePress is a static site generator powered by Vue.js that supports Markdown files. It can be used to create documentation and user guides and integrates with GitHub for version control.
3/23
Tasks
Mentorship Applications for Documentation
PENDING TOC REVIEW | Bevel: Tutorial on deploying fabric and besu on minikube | DOCUMENTATION | Bevel | 3 | 4 | 3 | 2 | 3 | |||||||||||||||||||
PENDING TOC REVIEW | Bevel: Documentation redesign | DOCUMENTATION RESEARCH | Bevel | 3 | 5 | 4 | 2 | 3.5 | |||||||||||||||||||
PENDING TOC REVIEW | BiniBFT - An Optimized BFT on Fabric | RESEARCHCODINGDOCUMENTATION | Fabric | 2 | 3 | 2 | 4 | 2.75 | |||||||||||||||||||
PENDING TOC REVIEW | Cacti - Documentation | DOCUMENTATION | Cacti | 3 | 4 | 3 | 3 | 3.25 | |||||||||||||||||||
PENDING TOC REVIEW | Document, Review, and Implement Hyperledger AnonCreds ZKP Cryptographic Primitives | DOCUMENTATIONCODING | AnonCreds, Ursa | 4 | 4 | 3 | 4 | 3.75 | |||||||||||||||||||
PENDING TOC REVIEW | Hyperledger Onboarding Mentor/Mentee Program | DOCUMENTATION | Onboarding Task Force | 4 | 5 | 5 | 5 | 4.75 | |||||||||||||||||||
PENDING TOC REVIEW | Improve Documentation for DRMan, Generate & Publish Github pages using mkdocs | CODING DOCUMENTATION RESEARCH | DID, Ursa, Aries | 3 | 4 | 2 | 3 | 3 | |||||||||||||||||||
PENDING TOC REVIEW | Learning Tokens @ Hyperledger Besu | CODING DOCUMENTATION RESEARCH | Besu, Latinoamerica Regional Chapter | 3 | 4 | 3 | 3 | 3.25 | |||||||||||||||||||
PENDING TOC REVIEW | Telecom Decentralized Identities Network (TDIDN) | CODING RESEARCH DOCUMENTATION | Telecom SIG | 4 | 4 | 3 | 5 | 4 |
Cacti
Bevel
Besu
FireFly
Ursa
4/3
3/20/23
Task 1 | Deliverable | Name | Date |
---|---|---|---|
3/28- | Survey for Meeting | Bobbi Muscara | 3/20 Survey : https://docs.google.com/forms/d/1wWGjjOTh4E0BuI7sLjTtXOK_40Q63CWDQk7lsMTbSoM/edit |
4/3 | Research Mentorship programs for Documentation | Bobbi | 4/3 Complete |
4/10 | Review Mentorship programs with doc. needs (table below) | ||
https://github.com/hyperledger/toc/issues/46
Project Best Practices task force
https://github.com/hyperledger-labs/documentation-template
Task 1: Determine Main Users
Determine Different user Groups
Business / Newcomer / Citizen
Maintainer / Coders
Wiki Contributor / SIG Member / Chair
Common styling guide:
Develop a styling guide that outlines the formatting, structure, and language that should be used in all Hyperledger technical documentation.
USER GROUP DOCUMENTATION
Task 2
Recommended common publishing platform depending on user:
Identify and recommend a publishing platform that projects can use to publish their documentation. This will help ensure consistency across projects and make it easier for users to find the information they need.
Task 3
Document best practices for creating documentation:
Create a document that outlines best practices for creating technical documentation, including information on tooling and how to target different audiences.
Task 4
Create a template repo that new projects can use for creating their documentation:
Create a template repository that new projects can use to create their documentation. This should include the
Task 5
Best Practices for creating Documentation:
Develop best practices for creating technical documentation. This should include guidelines for using appropriate language, structure, and formatting, as well as how to present complex technical concepts to different audiences. Additionally, it should provide guidance on the use of visual aids such as diagrams and screenshots.
Task 6
Available Community Resources:
Identify and compile a list of resources available to the community that can assist in creating documentation. This can include tools such as style guides, publishing platforms, and tutorials.
Task 7 Audience Specific Training Materials:
Documentation should be tailored to specific audiences, such as developers or users. Develop training materials specific to these audiences to help them understand and utilize the documentation effectively.
Task 8 Documentation "badge":
Develop a checklist that projects can use to ensure that their documentation meets the established standards. Projects that meet these standards can be recognized with a "Documentation Badge."
Task 9
New Project Guidelines:
Create guidelines for new projects that outline the documentation requirements they need to meet. This should include guidance on how to structure documentation, what types of content are required, and how to use the recommended tooling.
Task 10 Existing Project Updates:
Review and update the documentation for existing projects to meet the established standards. This will ensure that the entire Hyperledger community has access to high-quality technical documentation.
3/15/23
Mentorship Application
Hyperledger Documentation Standards
3/13/23
Introduction
The mission of the Documentation Standards Taskforce is to establish consistent and comprehensive documentation standards for the Hyperledger Foundation open-source blockchain platforms. Our goal is to provide developers, users, and other stakeholders with high-quality technical documentation that is accurate, accessible, and easy to understand. Our end goal is to ensure that the technical documentation for the Hyperledger community is of the highest quality, making it easier for developers to build on these platforms and for users to understand and utilize them effectively. Therefore, we aim to develop a set of standards that will be suggested to the Hyperledger projects that utilize the tools available to the community while also considering each project's unique features and characteristics. The purpose of this tone is to recognize that each Hyperledger project has a different team, with different maintainers who create and update documentation pages. Our task force will evaluate the current documentation environment and work collaboratively to establish standards and training materials and make the community aware of available resources.
Tasks to be Completed
Evaluation of the Current Environment | X |
Discovery of Publishing Platforms | X |
Best Practices for creating Documentation
| |
Determine Needs Existing Project Updates |
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
Time to complete
3-4 Months
Leader
Bobbi Muscara
Initial participant list
- Venkatraman Ramakrishna (Rama)
- Tracy Kuhrt
- John Carpenter
- Hardik Gupta
- Ben Weymouth
Meetings:
Mondays 12pm EST ( See calendar link)
Chat Channel
https://discord.com/channels/905194001349627914/1070733392020246620
References
Survey : https://docs.google.com/forms/d/1wWGjjOTh4E0BuI7sLjTtXOK_40Q63CWDQk7lsMTbSoM/edit
Current Environment
Survey Results:
https://docs.google.com/forms/d/1wWGjjOTh4E0BuI7sLjTtXOK_40Q63CWDQk7lsMTbSoM/edit#responses
Discovery of Publishing Platforms
Current Status of Hyperledger Documentation Platforms
- 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.
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
| 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" /> | https://hyperledger.github.io/caliper/ | 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 | https://github.com/hyperledger/cello/blob/main/README.md | 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. | https://hyperledger.github.io/firefly/ | https://hyperledger.github.io/firefly/ | 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 | https://rust-lang.github.io/mdBook/ | Documentation | Repositories | |
Solang | Built with Sphinx using a theme provided by Read the Docs. | https://Solang.readthedocs.io/en/latest/ How to run Solang on command line: https://Solang.readthedocs.io/en/latest/running.html | Blockchain-specific instructions for: Solana: https://solang.readthedocs.io/en/latest/targets/solana.html Substrate: https://solang.readthedocs.io/en/latest/targets/substrate.html |
Best Practices for creating Documentation
Available Community Resources: Hyperledger provides a number of paid developer tools and services for projects:
Technical Documentation: use markdown, GitHub pages, and Material for MkDocs.
Informal documentation and details (e.g. meeting notes, meeting agendas, long-term planning documentation, etc.): use the wiki (i.e. Confluence).
Develop:
General intro
App dev guide
System guide
Quick Start information
Target Audience
Maintainers
Developers
General guidelines
Be consistent - Consistency helps users follow and understand the documentation. By being consistent with your word choices, visual formatting, and style of communication, users know what to expect when they read the documentation. For example, use consistent sentence structures when writing step-by-step instructions.
Be simple but technically correct - Avoid technical jargon and assume the user isn’t an Ethereum expert. When an understanding of a complex Ethereum concept is required, you can refer users to external resources. For example, to explain how the EVM works, link to a resource such as the Ethereum Wiki.
Be proactive and suggest good practices - Anticipate users’ needs and guide them through a process. This often takes the form of notes or tips alongside the main explanation. Put yourself in the user’s shoes and consider what questions you’d have when reading the documentation.
Documenting good practices is also important. For example, instruct users to secure private keys and protect RPC endpoints in production environments.
Be informative but concise - Provide enough information to help users develop a mental model of how the software works without forcing them to read too much text or redundant detail. Cut down your text by using simple words and concise sentences.
Be inclusive - ConsenSys documentation aims to be inclusive to all users. Refer to the Google inclusive documentation guide and the Microsoft bias-free communication guide as starting points
Badging System for Technical Documentation
On-the-fly Style Guide for Hyperledger Publications.
Documentation
- The project basic documentation :This documentation must be in some media (such as text or video) that includes: how to install it, how to start it, how to use it (possibly with a tutorial using examples), and how to use it securely (e.g., what to do and what not to do) if that is an appropriate topic for the software. Users need documentation so that they can learn how to use the software. This documentation could be provided via the project website or repository, or even via hyperlink to some external information, so we do not specify exactly where this information
The documentation of an external interface explains to an end-user or developer how to use it. This would include its application program interface (API) if the software has one. If it is a library, document the major classes/types and methods/functions that can be called. If it is a web application, define its URL interface (often its REST interface). If it is a command-line interface, document the parameters and options it supports. In many cases it's best if most of this documentation is automatically generated, so that this documentation stays synchronized with the software as it changes, but this isn't required. The project MAY use hypertext links to non-project material as documentation. Documentation MAY be automatically generated (where practical this is often the best way to do so). Documentation of a REST interface may be generated using Swagger/OpenAPI. Code interface documentation MAY be generated using tools such as JSDoc (JavaScript), ESDoc (JavaScript), pydoc (Python), devtools (R), pkgdown (R), and Doxygen (many). Merely having comments in implementation code is not sufficient to satisfy this criterion; there needs to be an easy way to see the information without reading through all the source code. If the project does not produce software, choose "not applicable" (N/A).
Other
David Boswell
Hart Montgomery Arun S M Kamlesh Nagware – Thanks for your feedback and I see that you've each mentioned that having more resources at the graduated level would be helpful. Here are some ideas to consider, although it would also be really helpful to hear from people involved in projects about what additional help they'd be interested in.
- I think there is probably something around documentation and translation support for graduated projects that would be worth doing. If possible, perhaps we can make some budget available to bring in a technical writer, for example, to help with project docs?
- We could also make the resources available to Incubation projects time bound – for instance, an Incubation project could have a year to grow and mature and at the end of that time the TSC decides to either move it to Graduated or move it to the Labs.
- The project placement on the Hyperledger site does not currently provide a distinction between Graduated and Incubation projects since they're treated the same way now. We're looking at updating the site this year to give more prominent positioning to Graduated projects, so the priority placement item will become more of an incentive.
- The same is true of Workshops – this is a new concept so we have not yet seen the benefits to a project of running a workshop. After we've done a few of these we can analyze the outcome and if we can see a bump in users and contributors to a project after a workshop then this will become an incentive for Graduation status too.
Project participation and interface:
- CONTRIBUTING.md - How to contribute to this project
- INSTALL.md - How to install/quick start
- governance.md - How the project is governed
- roadmap.md - Overall direction of the project
- background.md - Background research
- api - Application Programming Interface (API), inc. data downloads
Criteria:
- criteria.md - Criteria for "passing" badge
- other.md - Criteria for other badges (silver and gold)
Development processes and security:
- requirements.md - Requirements (what's it supposed to do?)
- design.md - Architectural design information
- implementation.md - Implementation notes
- testing.md - Information on testing
- security.md - Why it's adequately secure (assurance case)
Evaluation and Ideas
- Standardize graphics and the glossary section for better concept lookups and user experience.
- Standardized common blockchain primer