Question: What is the usability of documentation from content and structure perspectives?
Documentation usability addresses the critical role of an open source project’s documentation by making sure that various users can understand it. Documentation usability contains issues of structure, content, jargon, and readability with the goal to foster understanding for the widest audience of contributors to the project.
- Technical Jargon — Documentation uses an appropriate level of technical jargon and provides an explanation for terminology as necessary to ensure the documentation is understandable for an entry-level contributor to the given project.
- Structural Clarity — Documentation is easy to follow and understand.
- Readability — Documentation uses language that is clear and concise, using common meaning words and short sentences, to ensure the documentation is understandable to people for whom the language is not native or those who may not follow similar shorthand conventions or inference patterns.
- Language Inclusion — Documentation avoids non-inclusive language (for example, ‘brogrammer’ language or exclusionary/derogatory language).
- Language Diversity — Documentation is available in a common vernacular for the intended audience and different languages.
- Time/Attention Diversity — Documentation is inclusive of people that have differences in the time they can spend on the documentation either reading or setting up/running commands. It is worthwhile to consider people with childcare or other caring roles that may pull their attention from their screens at any given point, so keeping documentation in smaller, more consumable blocks is preferable.
The usage and dissemination of health metrics may lead to privacy violations. Organizations may be exposed to risks. These risks may flow from compliance with the GDPR in the EU, with state law in the US, or with other law. There may also be contractual risks flowing from terms of service for data providers such as GitHub and GitLab. The usage of metrics must be examined for risk and potential data ethics problems. Please see CHAOSS Data Ethics document for additional guidance.
Data Collection Strategies
- Interview newcomers to determine how documentation helped the contributor to, (a) understand the contribution process, and/or, (b) complete the task.
Sample interview questions:
- Describe your experience with using the documentation to understand the contribution process.
- Describe your experience with using the documentation when you have a question about doing work in the community.
- Describe your experience with using the documentation to understand how to help outreach efforts.
- How comfortable were you with the number of technical terms present here? (adapt to survey using [Likert scale 1-5)
- Were there any terms or language you didn't understand?
- What suggestions do you have for improving the project’s policies, processes, or guidelines available to new contributors?
- After interviewing, the community can track responses to each prompt as
Negative experience, or
Neutral experienceand report these month-over-month to see improvement over time.
- Ask questions regarding readability and scannability such as; Does the documentation use organizing construct? Such as:
- Text and Code Blocks
- Bullets versus Paragraphs
- Walkthrough with intended users of the documentation. Observe how they interact and use the documentation and where they get stuck. This can be a video conference session where the user of the documentation shares their screen.
- Ask users of documentation to write a friction log and describe what issues they had with documentation. This gives concrete use cases for documentation editors to understand how to improve the documentation for the specific user.
- Consider if different versions of the documentation are available for different audiences. For example, a lightweight version and a very detailed version of the documentation.
- W3C Web Content Accessibility Guidelines
- W3C Web Accessibility Evaluation Tools List
- Some quick tests to evaluate web accessibility
- A group that specializes in Accessibility
- Thoughts on Accessibility metrics
- GNOME on Accessibility
- Paypal’s list of Guidelines for Accessibility
- The Core Infrastructure Initiative: Best Practices Badge
- Breaking Down Barriers to Kubernetes Contribution for Neurodivergent Individuals
- Friction Log
- Stanford: Screen Reader Testing
This metric was last reviewed on July 23, 2022 as part of the metrics revision process.