Victoria Johnson

Owned by Victoria Johnson
Last updated: Aug 11, 2023
2 min read

I am documenting my progress as the Best Practices Lead here.


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

  1. Conduct extensive analysis of existing practices and also identify areas of inconsistency and inefficiency.
  2. Collaborate with key stakeholders, including developers, maintainers, and community members, to gather insights, requirements, and feedback.
  3. Research industry best practices and identify suitable methodologies, tools, and frameworks that could be adopted within the Hyperledger ecosystem.
  4. Develop comprehensive documentation, guidelines, and templates covering documentation processes and version control.
  5. Organize training sessions and webinars to educate community members on the newly established best practices and encourage their adoption.
  6. Regularly monitor and assess the implementation of best practices, collecting feedback and addressing any issues or concerns.


Result

  1. Improve consistency and efficiency in documentation processes across projects.
  2. High-quality documentation that is accurate, accessible, and easy to understand, thus attracting more contributors and expanding the user base.




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.



Monday  

  • Goals for each sub-committee