GitHub survey: Incomplete documentation is the biggest problem encountered in open source
© Shutterstock / Nirat.pix
GitHub’s 2017 open source survey findings show that although documentation is highly valued, it is often overlooked. The survey also revealed that open source is the default when choosing software — most users are committed to open source, and always seek out open source options.
Nothing is perfect and open source is no exception. According to the findings of GitHub’s 2017 open source survey, there are a few problems that need to be fixed, namely poor documentation, negative interactions and the lack of female presence.
GitHub survey collected responses from 5,500 randomly sampled respondents sourced from over 3,800 open source repositories on GitHub.com, and over 500 responses from a non-random sample of communities that work on other platforms.
If you only want the overview, here it is:
- 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.
Documentation is either incomplete or outdated
There are a lot of problems that users encounter in open source but it seems that incomplete or confusing documentation is the most pervasive.
According to GitHub’s findings, 93 percent of the respondents noticed that incomplete or outdated documentation is a pervasive problem but 60 percent say they rarely or never contribute to documentation. GitHub encourages users to help a maintainer out and open a pull request that improves them whenever they run into documentation issues.
Furthermore, licenses represent the most important type of documentation not only to users but also to contributors. 64 percent of the respondents said that an open source licence will help them decide whether they want to use a project or not. Meanwhile, 67 percent said this aspect helps them decide whether to contribute.
The findings show that underrepresented groups (such as women) value documentation that clearly explain a project’s processes and users who didn’t grow up speaking English or read less-than-fluently prefer projects that have clear and accessible language.
Negative interactions have consequences
Negative interactions may not be so frequent but this doesn’t mean they are not visible. According to the findings, the most frequently encountered bad behavior is rudeness.
Almost 20 percent of respondents have personally experienced a negative interaction with another user in open source, but half of the total number of respondents have witnessed one between other people. The real problem is the fact that 21 percent of people who experienced or witnessed a negative behavior said they stopped contributing to a project because of it, and almost ten percent started working in private channels more often.
Gender imbalance remains profound
95 percent of respondents are men, three percent are women and one percent are non-binary. The findings show that women are about as likely as men (68% vs 73%) to say they are very interested in making future contributions, but less likely to say they are very likely to actually do so (45% vs 61%).
It seems that women are more likely that men to encounter language or content that makes them feel unwelcome (25% vs 15%) as well as stereotyping (12% vs 2%) and unsolicited sexual advances (6% vs 3%). They are also more likely than men to seek out help directly (29% vs 13%) from people they already know well (22% vs 6%), rather than ask for help from strangers in a public forum or channel.
One percent of respondents identify as transgender (including 9% of women in open source), and seven percent identify as lesbian, gay, bisexual, asexual, or another minority sexual orientation. 26 percent are immigrants (from and to anywhere in the world) and 16 percent are members of ethnic or national minorities in the country where they currently live.
Open source is the default when choosing software
Security is the most important feature when using any kind of software (86% extremely or very important) but users also care about stability and user experience (88% and 75% extremely or very important, respectively) when it comes to choosing software. However, less than 40 percent said user experience tends to be better, and 30 percent said that open source software is generally more stable than proprietary options.
Still, 72 percent say that they always seek out open source options when evaluating new tools.
The survey findings can be downloaded from GitHub.