Question: How easily can users and contributors find the information they are looking for in a project’s documentation?
Documentation discoverability is critical due to the role it plays in open source project’s inclusivity. If people cannot find and then easily navigate through the body of documentation, or find the answers they seek, they are less likely to use or contribute to the project thus decreasing the project ability to attract a diverse set of contributors. Documentation discoverability has the goal to ensure searchability and visibility as well as improve inclusivity across a diverse audience.
Visibility — Documentation is easy to find and reference.
Searchability — Documentation can easily be navigated by users based on their ability, and they can find the relevant information they need through search.
Method of Discovery — Identification of the ways in which people find the documentation
Inclusivity - Knowledge is shared more equitably among project contributors, and new contributors can more easily participate..
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
Survey project members:
Likert scale [easy to find - impossible to find] regarding the discoverability of documentation such as:
- Mailing list archived communication
- Mailing list membership management
- Chat channel archived communication
- Performing code reviews
- Process of getting code accepted
- Code of conduct
- Onboarding newcomers
- Licensing, trademark
- Project leadership
- Project releases
- Voting process
Multiple-choice checkbox: How do you discover project documentation?
- Documentation within the software
- Search engine
Multiple choice: Did you experience any challenges related to the discoverability of documentation when you started to participate in the project (e.g., language barriers, or structure of documentation)? Answer options:
- No challenges
- A few challenges
- Several challenges
- Many challenges
Open-ended follow-up question if the answer is anything other than “No challenges”:
- Describe an example of what challenge you experienced and when, how the challenge affected you, and how, if at all, you overcame the challenge.
- Open-ended follow-up question:
- What suggestions do you have for improving the project’s documentation regarding policies, processes, or guidelines available to new contributors?
Walkthrough with intended users of the documentation.
Observe how they interact and use the documentation and where they get stuck. For example, 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.
- Curse of Knowledge
- Knowledge Base 101
- 5 Tips for Making Documentation a Priority in Open Source Projects
- Building navigation for your documentation site: 5 best practices in design
This metric was last reviewed on July 24, 2022 as part of the metrics revision process.