...
- 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.