mastodon.social is one of the many independent Mastodon servers you can use to participate in the fediverse.
The original server operated by the Mastodon gGmbH non-profit

Administered by:

Server stats:

360K
active users

Greg Wilson

Arya et al 2024: "The Software Documentor Mindset" arxiv.org/abs/2412.09422 Explores why people voluntarily create documentation for open source software projects, how they pick topics, and other related factors; none of the findings are particularly surprising in retrospect, but that's not the same as saying I could have predicted them.

arXiv logo
arXiv.orgThe Software Documentor MindsetSoftware 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.

@gvwilson I'd love to see "what holds you back when writing docs". Social things will be obvious (yet super important), but I have lots of mental blocks like checked cross-references, testing of all code in docs, and lints, etc. This also makes it feel like it would be inappropriate to ask for doc help in a project that's doesn't meet such standards, though doing so is difficult in mixed language projects.

@jedbrown the authors' email addresses are in the preprint and I'm sure they'd be happy to hear from you.