Improving communities through documentation (2019)

talk, is the superpower that we can use to energize users and developers; it is an important part of the creation of a vibrant and inclusive community. While there are a number of roadblocks that can impede participation in a development community, many of those can be addressed with better documentation. The talk was a call for all projects to think about what they are trying to accomplish and to ensure that their documentation is helping to get there.

First, though, MacNamara started with a story. The fifth of Euclid's postulates holds that non-parallel lines must eventually cross. Not only has this postulate never been proved, but there are geometries where it is known to be false; these include hyperbolic spaces . Those spaces, though, are hard to visualize and hard to explain, a fact that inhibited research into them for two centuries.

In 1997, Diana Taimina realized that crochet could be used to create a model of a hyperbolic space; this model is now the standard way of explaining the whole idea. The visualization of hyperbolic spaces is, MacNamara said, a problem that had gone unsolved for centuries for a simple reason: the field of mathematics was closed to women. What else are we losing, she asked, when we exclude the talents held by large parts of our population?

Open-source software has just such a problem, even if one looks only at gender and ignores (for now) many other potential diversity issues. Surveys have shown that only about 3% of the open-source development community is female; the situation is very much like the 18th-century mathematics field. She would like to improve that situation, increase diversity in our communities, help the process of inclusion, and thereby create equity in the field.

Contributor types

Toward that end, Google commissioned a study looking at how people enter open-source communities, with the idea of finding ways to attract more contributions. It asked who the users are, what their journey to becoming a contributor is like, what their information needs are, and how we tend to lose them. The group interviewed 18 subjects, some of whom were contributors and others not, and came up with five archetypes to describe them:

• Leaders, like "Rory", who are active in their communities; their activity is generally supported at work. Rory's biggest need is usually help in growing the community.
• "Avery", who is convinced about open source, but whose participation is held back. Avery knows the value of contributing and feels safe in the community, but is unable to fully participate, perhaps because of a lack of support at work.
• Competent people like "Taylor", who are not yet convinced of the value of participating in the community. Taylor does contribute, generally in the form of bug fixes, but doesn't see the point of doing more. Taylor may be skeptical about the owners of a project and is not sure what benefit would be gained from participating more fully.
• Curious people like "Parker" who do not yet contribute — we all began as Parker, she said. Parker is curious about how to get involved but faces a number of barriers. They may not be technically advanced or understand how open-source development works; they almost certainly do not have support.
• Lurkers; MacNamara didn't really talk about this unnamed group at all.

Looking at Parker, MacNamara delved into how such a person would pick a project. There are a few phases involved, the first of which is assessment, where the objective is to eliminate any unsuitable projects from consideration. What language does the project use? What are the requirements for participation? This phase also involves a look at the reliability of the project — is it likely to be around for some time? Parker will probably start by looking at commit activity, but then will move on to the project's documentation. They might not read the documentation at this point, but its presence indicates that the project is healthy.

After that, though, a potential contributor will want to obtain a better understanding of how the project works, and good documentation becomes critical. What is the overall architecture of the project? What are its use cases? They will want to be sure that this information is there and accessible.

The next phase is adoption and, at some point, Parker will certainly run into some sort of problem. It's software, after all. That is the make-or-break point for a future contributor, she said. They may succeed in fixing the problem and will want to contribute the fix back, but that's where the roadblocks show up. Sending a contribution to a project can be scary; one has to make oneself vulnerable to do so. An employer may stop the process, or hostile feedback may drive people away; either way, they don't contribute, and that is bad for everybody involved.

What can help with this process? Documentation (or the lack thereof) is often the biggest barrier that potential contributors encounter.

Documentation for an inclusive project

But is documentation really necessary? Established members of a project will often say that contributors should be able to just read the code to get the answers they need. There are a number of problems with that answer, but MacNamara had one in particular to point out: women have less leisure time available for activities like "just reading the code" than men do. The numbers vary, but women all over the world still do significantly more unpaid work than men. Having the time to contribute to a software project is a privilege, and it's one that women tend not to have the way men do. So they can't just go read the code to get the answers they need.

Another suggested alternative is to simply ask for help. But not everybody experiences the community in the same way. People who have had bad experiences, harassment for example, are going to be reluctant to ask for help publicly. For them, the lack of documentation is a significant barrier to contribution. Others may not have strong English skills, which makes it harder to ask for help; once again, documentation can help.

MacNamara repeated that contributing to an open-source project requires making oneself vulnerable. In many projects, people are afraid to ask questions — or even to answer them. One of the best things to do to create a more inclusive community is to build psychological safety for participants. Creating clear and effective documentation is a big step in that direction.

In fact, she said, good documentation can help people at all four of the stages listed above. It can help people decide whether a given project is right for them by describing the languages used, what the use cases are, what platforms the project is built on, etc. New contributors can start more quickly with "getting started" guides, tutorials, and documentation with good and well-designed navigation. Documentation can help to convince managers to support the work by covering use cases, contribution requirements, success stories, and so on. Leaders will benefit from the ability to bring contributors in more easily.

The required documentation takes a few different forms. Those considering adopting a project will need "standard engineering documentation" like API references, tutorials, and troubleshooting guides. There should be information about getting help and pointers to resources like a project's social media presence. Good navigation, and especially good search features, are critical.

Contributors need the above documents and more. There should be documentation for moderators and reviewers describing how the project responds to people. There should be welcoming documents for new users and contributors. And, of course, there need to be guidelines for the documents themselves.

To get there, she said, a project should recognize and reward good work on documentation. Non-code contributions are vital to a project's health; they provide a project with a lot of value and stability. When the documentation is good, everybody wins.

To summarize, she said that the lack of good documentation is a barrier to contributions, and to contributions from women in particular. Psychological safety is paramount in an inclusive project, and documentation helps to create that. Documents that clearly describe a project empower contributions. Tribal knowledge concentrates power in the hands of a privileged few, while good documentation gets knowledge out of people's heads and makes it more widely available. Knowledge, she said, is power; when we make knowledge accessible, we build equality.

[Your editor thanks the Linux Foundation for supporting his travel to the event.]

to post comments)