Pratyay Banerjee

Owned by pratyaybanerjeex
Last updated: Jun 02, 2023
2 min read

Comprehensive documentation and guides are crucial to effectively utilize tools and frameworks. Insufficient guidance can deter users and hinder adoption. The following are resources to enhance user experience and foster a deeper understanding of Hyperledger blockchain projects via updating and improving the documentation and start guides. By providing clear and comprehensive resources, we can attract more traffic (potential contributors), & create a thriving community.✨

Suggested improvements (Template) ⚡

  1. Examples: Provide practical code examples, interactive demos, or use cases that demonstrate the usage of the project or feature.

  2. Release Notes: Maintain a separate section to document the release notes for each version or significant updates of the project. (Vital in long-run)

  3. Bridging the Gap: Enhancing clarity and addressing gaps in Hyperledger Documentation to provide a comprehensive resource for users. (Requires comprehensive analysis)

  4. Additional Resources: Provide links or references to external resources, such as tutorials, articles, videos, or related projects, that can further enhance users' understanding and usage of the project.

  5. Support and Community: Provide information about Hyperledger's official Discord server, mailing lists (if exist), and encourage community engagement. 

  6. Security (& Security Best Practices): Security-related considerations, best practices, and guidelines for users and contributors.

Extras (Template) ⚡

  1. License Obligations: Include any supplementary licensing factors to be mindful of when making contributions.

  2. Optimize Readability: By incorporating visual elements (screenshots, diagrams, flowcharts, etc.) on the web pages, we can enhance the overall user experience and make the content more visually appealing and engaging. Moreover, we can conduct readability test (Flesch-Kincaid) as per-need & obtain a readability index (e.g. Gunning Fox Index) which will help identify areas for betterment.
  3. Include Description to URLs: This initiative will facilitate easier navigation with greater confidence, easily accessing the desired information and maximizing their engagement with our platform. (GDPR compliance) 
  4. Troubleshooting: Include a troubleshooting guide or section that addresses common issues and provides solutions or workarounds. (optional)

Documentation Task Force ⚡

  1. Best Practices: Categorize best practices based on specific domains or categories.

  2. Improving User Experience: Implementing Friction Logs for Enhanced Accessibility and Usability of Documentation. (especially for newcomers)
  3. Enhanced Query Review/Feedback Mechanism: Streamlining and enhancing the query/feedback management process on Discord to better support and address the questions and inquiries raised by contributors.
  4. Enable Discussions: Facilitate collaborative discussions and engagement by leveraging GitHub's Discussions (feature).

A few References ⚡

  1. The Mayfield Handbook of Technical Scientific Writing (Authored by Leslie C. Perelman • James Paradis • Edward Barrett)
  2. Technical Documentation in Software Development: Types, Best Practices, and Tools
  3. Docs for Developers — An Engineer's Field Guide to Technical Writing (By Jared Bhatti, Zachary Sarah Corliessen, Jen Lambourne, David Nunez & Heidi Waterhouse)
  4. The documentation System (by Divio)


♦ Added a Stale bot for monitoring open issues & also integrated a few PR & Issue templates for contributors →  https://github.com/hyperledger-labs/documentation-template/pull/10 (Merged)

♦ Add Best Practices (In progress ⌛)