GitHub Survey: Open Source Is Popular, Plagued by Poor Docs and Rude People

Despite the popularity of open source software development, the growing movement is plagued by poor documentation and negative interactions -- primarily rudeness -- among developers, according to a big new survey from GitHub Inc.

The popular source code/version control repository and development platform just published the results of its Open Source Survey, including data from more than 5,500 open source participants who were randomly sampled from more than 3,800 projects on GitHub.com, along with more than 500 responses sourced from communities that work on different platforms. Although primarily driven by GitHub, the effort was also helped out by researchers from academia and the development industry.

The results are available in an open data set -- the project is hosted on GitHub -- that reveals the attitudes, experiences and backgrounds of developers who use, build, and maintain open source software, said the company, which said it's providing the information for the community, researchers and data wonks to study.

Key insights as detailed by the company include:

Documentation is highly valued, frequently overlooked, and a means for establishing inclusive and accessible communities.

Negative interactions are infrequent but highly visible, with consequences for project activity.

Open source is used by the whole world, but its contributors don't yet reflect its broad audience.

Using and contributing to open source often happens on the job.

Open source is the default when choosing software.

Regarding the "negative interactions" finding (which we've reported on before), GitHub said: "18 percent of respondents have personally experienced a negative interaction with another user in open source, but 50 percent have witnessed one between other people. It's not possible to know from this data whether the gap is due to people who experienced such interactions leaving open source, or broad visibility of incidents."

The most frequently cited negative interaction was rudeness, witnessed by 45 percent of respondents, and experienced by 16 percent, followed by name calling (20 percent witnessed, 5 percent experienced) and stereotyping (11 percent witnessed, 3 percent experienced). There was much less reporting of more serious transgressions, such as sexual advances, stalking or doxing. Those were encountered by less than 5 percent of respondents and experienced by less than 2 percent, but cumulatively witnessed by 14 percent of respondents and experienced by 3 percent.

[Click on image for larger view.]
Negative Behavior in Open Source (source: opensourcesurvey.org)

Furthermore, such negative interactions have a real-world effect on open source projects, the study revealed, as 21 percent of developers who experienced or witnessed such behavior said it influenced them to stop contributing to a project, with 8 percent of respondents saying they started working in private channels more often.

GitHub also provided some free advice based on these findings. "Negative interactions impact many more than the immediate participants, so address problematic behavior swiftly, politely, and publicly, to send a signal to potential contributors that such behavior isn't typical or tolerated," the company said.

Also, the company continued: "Tooling that allows people to address problematic behavior directly is the most effective way of addressing harassing behavior. Blocking a user was reported to be more effective than enforcement from third parties like maintainers, ISPs/hosting services, or even legal resources. Give people tools to protect themselves."

The report also revealed the sorry state of open source documentation.

"Documentation helps orient newcomers: how to use a project, how to contribute back, the terms of use and contribution, and the standards of conduct in a community," the report states. "Improving that documentation is an impactful way to contribute back to open source."

Key documentation-related findings as listed by GitHub include:

Incomplete or outdated documentation is a pervasive problem, observed by 93 percent of respondents, yet 60 percent of contributors say they rarely or never contribute to documentation. When you run into documentation issues, help a maintainer out and open a pull request that improves them.

Many people participate in open source on the job, where confidence in the terms of use is critical. Unsurprisingly, licenses are by far the most important type of documentation to both users and contributors: 64 percent say an open source license is very important in deciding whether to use a project, and 67 percent say it is very important in deciding whether to contribute.

Documentation helps create inclusive communities. Documentation that clearly explains a project's processes, such as contributing guides and codes of conduct, is valued more by groups that are underrepresented in open source, like women.

Nearly a quarter of the open source community reads and writes English less than ‘very well.' When communicating on a project, use clear and accessible language for people who didn't grow up speaking English, or read less-than-fluently.

[Click on image for larger view.]
Problems Encountered in Open Source (source: opensourcesurvey.org)

Other highlights lifted from the report include:

The gender imbalance in open source remains profound: 95 percent of respondents are men; just 3 percent are women and 1 percent are non-binary. Women are about as likely as men (68 percent vs 73 percent) to say they are very interested in making future contributions, but less likely to say they are very likely to actually do so (45 percent vs 61 percent).

Half of contributors say that their open source work was somewhat or very important in getting their current role. Open source work helps people build their professional reputation. Improving contributor representation can help create a more representative tech sector overall.

70 percent of respondents are employed full- or part-time, and 85 percent of those contribute in some way to software development (for example, developers, designers, other roles in the software industry) frequently or occasionally in their main job.

Virtually all (94 percent) of those who are employed use open source at least sometimes in their professional work (81 percent use it frequently), and 65 percent of those who contribute back do so as part of their work duties.

Open source's comparative advantage is in security: security is among the most important features when using any kind of software (86 percent extremely or very important). Security is the only dimension we asked about where a majority of users believe that open source software is usually better than proprietary software (58 percent).

Users also care about stability and user experience (88 percent and 75 percent extremely or very important, respectively) when it comes to choosing software, but on these dimensions fewer were convinced of open source's superiority: only 36 percent said user experience tends to be better, and 30 percent said that open source software is generally more stable than proprietary options.

"We hope you'll use the data to inform decisions about community, tooling, and prioritization of work; understand the needs and experiences of different parts of the community; and do new and interesting research on a remarkable system of peer production that powers so much of modern life," GitHub said in a blog post on Friday.