Documentation Accessibility

Data Collection Strategies

• Use a tool that evaluates screen-reader friendliness. (5) (6) to determine if the documentation is screen-reader friendly?
• Interview newcomers to figure out how documentation helped with, (a) understanding the contribution process, and/or, (b) helping to complete tasks in a project. Sample interview questions:
  • What is your experience with using the documentation to understand the contribution process?
  • What is your experience with consulting the documentation when you have a question about doing work on the project?
  • Were you comfortable with the technical terms present in the documentation?

• Survey project members

  • Matrix item: When you need to locate information about this project’s processes, policies, or guidelines, which of the following describes your experience? (2)

  • Matrix rows can be:

    • Mailing list communication
    • Chat communication
    • Performing code reviews
    • Process of getting code accepted
    • Code of conduct
    • Onboarding newcomers
    • Licensing
    • Trademark
    • Add new Committers/Maintainers
    • Project releases
    • Voting process
    • Installation procedures
    • Feature development
    • API integration
    • Test suites
    • Architecture overview
    • User guide
  • Matrix columns can be:
    • Always easy to find
    • Easy to find
    • Difficult to find
    • Very difficult to find
  • Multiple choice: Did you face any challenges related to the accessibility of documentation when you started to participate in the project (e.g., language barriers, discoverability of documentation, the structure of documentation)? (2)
  • Answer options:
    • No challenges
    • A Few challenges
    • Several challenges
    • Many challenges
  • Open-ended follow-up question if the answer is not “No challenges”: Describe an example of when you experienced the challenge, how the challenge affected you, and how, if at all, you overcame the challenge.
  • Open-ended question: What suggestions do you have for improving the project’s policies, processes, or guidelines available to new contributors? (2)
• Look for organizing constructs regarding readability and scannability such as:
  • Headings
  • Text and Code Blocks
  • Bullets or Paragraphs
  • Anchors
• Evaluate searchability by considering:
  • How easily can this documentation be found by a user?
  • How easily can a user find what they require within the documentation?
  • Is the document easy to navigate with a keyboard?
• Provide a quick micro-survey with only one question to readers of the documentation (i.e., bottom-page or popup when leaving documentation page):
  • Yes/No question: Was this documentation page accessible to you?
  • Likert Scale [1-x]: How accessible was this documentation to you?
  • Short Answer: How do you feel about the accessibility of the documentation?
• 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 documentation are available for different audiences? For example, a light-weight version and a very detailed version

Filters

• User needs (e.g., visual impairment, cognitive diversity)
• Language version of the documentation
• Documentation type (e.g., quick-start guide, API reference)

Visualizations

• None specified