Hey Everyone!
I will be mentioning my ideas here for the documentation task force.
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:
Best Practices Badges / Templates
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."
- I'm really missing an export function, like a PDF, as done by the Fabric docs.
These are the current issues I can think of that probably arose for other projects too at some point, and could probably be subjected to some Hyperledger-level guideline/best practice/policy.