Skip to content

Latest commit

 

History

History
83 lines (65 loc) · 5.09 KB

documentation-usability.md

File metadata and controls

83 lines (65 loc) · 5.09 KB
Raw

Documentation Usability

Question: What is the usability of documentation from content and structure perspectives?

Overview

Documentation usability assesses how well an open-source project’s documentation serves diverse contributors by ensuring clarity, readability, inclusiveness, and accessibility. This metric addresses various documentation attributes—such as content structure, readability, language inclusion, and time accessibility—to make it more approachable for a broad audience. Additional objectives it addresses includes:

  • Technical Jargon — Documentation limits technical jargon to an appropriate level and provides clear explanations to ensure it is understandable for entry-level contributors.
  • Structural Clarity — Documentation is well-organized and easy to follow.
  • Readability — Documentation uses clear and concise language, avoiding complex jargon or shorthand to ensure accessibility for non-native speakers or those unfamiliar with specific conventions.
  • Language Inclusion — Documentation avoids exclusionary or non-inclusive language.
  • Language Diversity — Documentation is accessible in multiple languages to meet the needs of diverse audiences.
  • Time/Attention Diversity — Documentation is divided into manageable sections for readers who may have limited time or need frequent breaks, such as individuals with caregiving responsibilities.

Want to Know More?

Click to read more about this metric.

Data Collection Strategies

Community leaders and documentation editors can collect data on documentation usability by:

  • Interviews with Newcomers:

    • Inquire about how the documentation helped newcomers understand contribution processes and complete tasks.
    • Sample questions:
      • Describe your experience with the documentation for understanding the contribution process.
      • Describe your experience with the documentation when you had questions.
      • How comfortable were you with the technical terms used?
      • Were there terms or language you found confusing?
      • What suggestions do you have for improving the documentation?

  • Observational Sessions (Walkthroughs):

    • Conduct live walkthroughs with users, observing how they interact with the documentation and noting any challenges they encounter.

  • Friction Logs:

    • Invite users to create a friction log, documenting any difficulties they experience while using the documentation.

  • Readability & Scannability Assessment:

    • Assess if the documentation uses clear organizing constructs, such as:
      • Headings
      • Code/Text Blocks
      • Bulleted lists
      • Anchors

  • Documentation Versions:

    • Evaluate if different versions are available to serve varying audience needs, such as simplified and detailed versions.

Filters

This metric can be filtered by:

  • Type of user (e.g., newcomers, experienced contributors)
  • Language version of the documentation
  • Type of documentation (e.g., quick-start guide, API documentation, installation guide)

Visualizations

  • None specified

References

Contributors

  • None Specified

Additional Information

To edit this metric, please submit a Change Request here. For referencing this metric in software or publications, use this stable URL: https://chaoss.community/?p=3532