Logo
ScienceStack
Table of Contents
Fetching ...
Sign In

The Software Documentor Mindset

Deeksha M. Arya, Jin L. C. Guo, Martin P. Robillard

TL;DR

The paper investigates why and how volunteers contribute software documentation by conducting 26 semi-structured interviews and applying qualitative analysis. It identifies 16 codified considerations across three dimensions—motivations, topic selection techniques, and styling objectives—and clusters them into five software documentor mindsets, forming a framework to reason about documentation contribution. The Mindset framework is validated via member checking and discussed in terms of balancing multiple mindsets, challenges, and potential extensions to other documentation contexts. The work offers implications for information seeking and tool design, emphasizing the documentor’s perspective and suggesting pathways for improving documentation quality and discoverability in the software ecosystem.

Abstract

Software technologies are used by programmers with diverse backgrounds. To fulfill programmers' need for information, enthusiasts contribute numerous learning resources that vary in style and content, which act as documentation for the corresponding technology. We interviewed 26 volunteer documentation contributors, i.e. documentors, to understand why and how they create such documentation. From a qualitative analysis of our interviews, we identified a total of sixteen considerations that documentors have during the documentation contribution process, along three dimensions, namely motivations, topic selection techniques, and styling objectives. We grouped related considerations based on common underlying themes, to elicit five software documentor mindsets that occur during documentation contribution activities. We propose a structure of mindsets, and their associated considerations across the three dimensions, as a framework for reasoning about the documentation contribution process. This framework can inform information seeking as well as documentation creation tools about the context in which documentation was contributed.

The Software Documentor Mindset

TL;DR

The paper investigates why and how volunteers contribute software documentation by conducting 26 semi-structured interviews and applying qualitative analysis. It identifies 16 codified considerations across three dimensions—motivations, topic selection techniques, and styling objectives—and clusters them into five software documentor mindsets, forming a framework to reason about documentation contribution. The Mindset framework is validated via member checking and discussed in terms of balancing multiple mindsets, challenges, and potential extensions to other documentation contexts. The work offers implications for information seeking and tool design, emphasizing the documentor’s perspective and suggesting pathways for improving documentation quality and discoverability in the software ecosystem.

Abstract

Software technologies are used by programmers with diverse backgrounds. To fulfill programmers' need for information, enthusiasts contribute numerous learning resources that vary in style and content, which act as documentation for the corresponding technology. We interviewed 26 volunteer documentation contributors, i.e. documentors, to understand why and how they create such documentation. From a qualitative analysis of our interviews, we identified a total of sixteen considerations that documentors have during the documentation contribution process, along three dimensions, namely motivations, topic selection techniques, and styling objectives. We grouped related considerations based on common underlying themes, to elicit five software documentor mindsets that occur during documentation contribution activities. We propose a structure of mindsets, and their associated considerations across the three dimensions, as a framework for reasoning about the documentation contribution process. This framework can inform information seeking as well as documentation creation tools about the context in which documentation was contributed.

Paper Structure

This paper contains 22 sections, 2 figures, 5 tables.

Table of Contents

  1. Introduction
  2. Related Work
  3. Documentation motivations
  4. Documentation creation practices
  5. Mindsets in Software Engineering
  6. Study Design
  7. Informant Recruitment
  8. Data Collection
  9. Qualitative Analysis
  10. Mindset Elicitation
  11. Validation
  12. Trade-offs
  13. Dimensions of the Software Documentation Contribution Process
  14. Motivations
  15. Topic selection techniques
  16. ...and 7 more sections

Figures (2)

  • Figure 1: Framework of documentors' mindsets and their associated considerations across the three dimensions of the documentation contribution process, i.e. motivations, topic selection techniques, and styling objectives, based on interviews with 26 documentors.
  • Figure 2: Agreement responses of the 17 respondents to the validation questionnaire.