Documentation Usability

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 in documentation either reading or setting up/running commands. It is worthwile to consider people with childcare or other caring roles that may pull their attention from their screens at any given point.


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 amount 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 Positive experience, Negative experience, or Neutral experience and report these month-over-month to see improvement over time.
  • Ask questions regarding readability and scannability such as: Does the documentation use organizing constructs, such as:
    • Headings
    • Text and Code Blocks
    • Bullets versus Paragraphs
    • Anchors
  • 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 of the documentation.