Interested projects
Monday
- Goals for each sub-committee
Tuesday 11 July 2023
Goals for Best Practices sub-committee
- Identify and promote industry-standard practices for documentation within the Hyperledger ecosystem
- Consistent and coherent documentation enhances readability, usability, and maintainability.
- These guidelines will cover various aspects, such as document structure, writing style, code examples, versioning, and maintaining documentation consistency.
- By adhering to these best practices, project teams will be able to produce documentation that is of the highest quality, ensuring a seamless experience for users and developers.
Who is our audience?
- New contributors
- Existing contributors
- Developers
- End-users
What makes a bad documentation?
- Unreliable content based on intuition and no prior research.
- Complex topics.
- Not aligned for a global audience.
- Uses acronyms without introductions.
- Grammatical errors.
- No use of whitespaces, headings, and lists.
- No visual representation.
What makes a good documentation?
- Use of accepted Style Guide.
- Accurate and evergreen content.
- Prior audience analysis.
- Solves a specific problem.
- Follows grammatical rules and punctuation.
- Concise and easy-to-understand content.
- High-quality visual representation.
- Provides links to sources.
- Use of appropriate sections, headings, fonts, lists, and whitespaces - the document is skimmable.
- Engaging and user-friendly content.
- Use of active voice.
Friday
Situation
The Documentation Task Force aims at establishing consistent and comprehensive documentation standards for the community platforms.
Task
As the Best Practices sub-committee, our task is to standardize documentation and enhance overall project efficiency across the Foundation.
Action
- Conduct extensive analysis of existing practices and also identify areas of inconsistency and inefficiency.
- Collaborate with key stakeholders, including developers, maintainers, and community members, to gather insights, requirements, and feedback.
- Research industry best practices and identify suitable methodologies, tools, and frameworks that could be adopted within the Hyperledger ecosystem.
- Develop comprehensive documentation, guidelines, and templates covering documentation processes and version control.
- Organize training sessions and webinars to educate community members on the newly established best practices and encourage their adoption.
- Regularly monitor and assess the implementation of best practices, collecting feedback and addressing any issues or concerns.
Result
- Improve consistency and efficiency in documentation processes across projects.
- High-quality documentation that is accurate, accessible, and easy to understand, thus attracting more contributors and expanding the user base.