Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Our taskforce is mean to foster open discussion and create a place for new ideas on the betterment of Hyperledger project documentation. Thus we would like to begin with six seven guiding principles and six seven specific recommendations that intertwine with those guidelines. 

...

  1. Standardization improves adoption of projects within the Hyperledger Ecosystem
  2. Each project should utilize a standard Location for Documentation: we recommend ReadtheDocs
  3. Any documentation hosting platform used should leverage a common Markdown Language, theme and interface. 
  4. Templates exist and therefore could be helpful in standardizing documentation pages. 
  5. Recognize and Resolve any tension between standardization (common template) with the implicit uniqueness of each Hyperledger project.
  6. Standards should be reflected in a consistent manner such as a badging system or checkmark awarded for adherence to these principles
  7. Allow for community involvement to avoid a strictly top-down approach; instead, reflect the values of the open-source community 

SPECIFIC RECOMMENDATIONS: 

  1. Standardize documentation content to promote increased usage and project adoption 
  2. Re-factor any existing inconsistencies in style, graphics, tables, bullet points, readability, links, and content usefulness for all projects to better serve future and current Hyperledger projects. 
  3. Current / Future Hyperledger Projects should both utilize the a standardized and agreed upon documentation pattern
  4. The Fabric documentation pattern could serve as a template: ReadtheDocs exists as the main source of non-code truth, GitHub for all code truth, and a Hyperledger Wiki page for Community related items and badging. 
  5. Standardize graphics and the glossary section for better concept lookups and user experience. 
  6. All Projects can leverage Discord: include or “pin” documentation relevant posts. (currently all are not pinned) 
  7. Utilize a survey to reflect the voice of the various unique projects that have documentation pages in disparate themes with varying styles and layouts. 

Tasks to be completed

  • Determine The Current Status of all Projects/Tools/Libraries
Status: Completed
  • Examine the current process used for documentation
Status: Completed
  • Create Standards / Best Practices for the Community
Status: In Progress
  • Create Documentation Best Practice badging system.
Status: In Progress

...