Hey Everyone!
I will be mentioning my ideas here for the documentation task force. As I am the Committee Chair for Templates. I will be focusing and working on templates for GitHub and documentation.
Initial Ideas :
GitHub templates and best practices :
- Creating a standard pull request template for the GitHub repository.
- Creating a standard issue template for the GitHub repository.
- Using automation for closing the issue and PR.
- Creating coding guidelines
Project templates and best practices :
A standard documentation template for all projects should be there. The template should include the following:
- Purpose of the project so that users can understand what the project is about, enhancing user experience.
- Describe how to use the project, the mechanism, and the functionalities of various features. Make the reader understand the technology, before using it. Gives instructions on how to do the specific task. It consists of steps that need to be followed.
- Provide relevant links, code snippets, and algorithms.
- Provide images, graphics, tables, flow charts, user flow, etc.
- Feedback from users
- Conclusion and people to contact for more information (maintainers, project mentor)
Resources:
Created a pull request template: https://github.com/hyperledger-labs/documentation-template/pull/12 (merged)
Had a conversation with the Caliper maintainer about enhancing the Caliper documentation.
The doc uses a custom template (https://hyperledger.github.io/caliper/, https://github.com/hyperledger/caliper/tree/gh-pages), which is designed pretty nicely, but there are some usability and maintainability issues:
- Accessibility options are not provided and would probably require manual implementation.
- Versioning of the documentation is manual and tedious (https://github.com/hyperledger/caliper/tree/gh-pages/docs), although it makes bug fixes or updates possible per version. But it's decoupled from the source code, so a separate PR must be submitted for the doc changes each time, making the update "not atomic."
- They are missing an export function, like a PDF, as done by the Fabric docs.
These are the current issues that arose for other projects too at some point, and could probably be subjected to some Hyperledger-level guideline/best practice/policy.
About Anoncreds: Two things they are planning, for now, is MkDocs site for documentation (https://github.com/hyperledger/anoncreds-rs), similar to https://aca-py.org/. This is just a idea as they don't know what content to put in there. They suggested that they could use the content of their workshop. But I didn't understand what he was talking about.
Another item would be an editorial review/corrections of the specification for consistency and completeness.
I need to discuss with him the documentation goals of Anoncreds. Not sure in what I have to contribute to.
Reference
Best Practices Badges / Templates