This metric is a release candidate. To comment on this metric please see Issue #313. Following a comment period, this metric will be included in the next regular release.

Documentation Discoverability

Question: How easily can users and contributors find the information they are looking for in a project’s documentation?

Description

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 diverse participants. Documentation discoverability has the goal to ensure searchability and visibility as well as improve inclusivity across a diverse audience.

Objectives

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..

Implementation

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?

  • Website
  • Repositories
  • Documentation within software
  • Search engine
  • Other

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 to 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.

Resources