How can you empower your community to be productive with and within your open source project?
When the concept of open source first emerged, people collaborated on projects very intentionally. Without today’s vast internet and information retrieval systems, the network of people (largely researchers) working on these shared systems largely grew via word-of-mouth. If you were working on a piece of software with folks outside of your institution, you likely would have communicated with them directly prior to them ever viewing a single line of code.
Even as more of the world gained access to the internet, finding information was a challenge. Usenet, a distributed discussion platform that came out of University of North Carolina at Chapel Hill and Duke University in 1980, arrived on the scene as a popular way to discover and communicate about software with freely available source code. Still, the effort needed to start using or contributing to a new project was high.
In order to find resources that you needed, such as source code or documentation (if any existed), you’d generally have to contact the author of the project. But eventually, web search improved, and with the rise of hosting and distribution platforms such as SourceForge it became much easier to find information about how to use and contribute to open source. Improvements in infrastructure, hardware, and computer science reduced the cost of experimentation and simultaneously increased the reach of freely modifiable and distributable software.
Barriers to people embracing open source started falling away.
Breaking down the barriers to open source
Open source is more accessible to new contributors than ever before, in part due to the user experience improvements pushed forward by platforms such as BitBucket, GitHub, and GitLab. They provide a way to discover new repositories and view their source. This means that you can browse and understand a project before becoming deeply invested. It has the added benefit for people with resource constraints, such as disk space or network bandwidth, because you no longer have to clone an entire repository (copy the files to your computer) in order to view its contents.
That said, there’s still a fair amount of improvement that can be made to the open source experience.
Four ways to empower open source users and contributors
Last time, we extended the initial social model of open source by outlining why open source projects should provide information about how they operate. This time, we’ll explore how projects can take a similar approach to helping users and contributors engage with them.
1. Documentation
Technical documentation existed long before the first line of code. Good documentation rests at that intersection between art and science, with technical writing expertise being highly sought-after in open source projects. Creating documentation for open source poses several challenges, including the sheer variety of audiences that need the docs! One of the most effective ways that a project can lower barriers to becoming involved is by specifying not only where documentation lives but also what type of documentation is available.
Consider the example set by the Python programming language, which points to several sets of documentation targeting different skill levels and roles.
2. Issues
While many projects these days choose to take reports of issues alongside where their code is hosted, some prefer to use an open source or third-party solution, such as Bugzilla or Trac. Wherever a project takes reports of issues and discusses them, making it very clear where community members should report current issues makes it an easier experience for them. As a side benefit, it lowers costs for maintainers by reducing the amount of redirection they need to do.
Jaeger sets a good example of this, by specifying where its issue trackers live, as well as where to file various types of issues.
Bonus points if a project publishes guides or templates for how to file issues!
3. Discussion
The frequency of communication between maintainers and users is of increasing importance to adopters, and can be a factor when making technology decisions. However, facilitating conversation between contributors and users alike signals a thoughtfulness and intentionality that benefits all participants in the project’s community. Projects that make a point of documenting official channels for discussion encourage the growth of a healthy community, allowing community members to support each other.
An example is how Apache Beam lists its various discussion fora and when to use each.
4. Contributing
As the complexity of software increases, so does the complexity of contributing to open source. Projects may have language-specific style guidelines that they ask modifications to follow, or processes that must be adhered to when a new contributor wants to pick up a bug to fix. While these working agreements might on occasion seem overly prescriptive to prospective contributors, they are there to maximize the success of everyone involved. Contributors minimize the amount of wasted effort, and maintainers minimize the amount of back-and-forth answering questions and requesting changes in reviews.
Generally, setting these expectations improves morale!
Inkscape’s CONTRIBUTING.md file outlines some general guidance as well as instructions about decision-making, building, testing, and documentation.
Along the same lines of providing contributor guidelines is documenting processes that architectural development should follow, such as how Bazel calls out how to make larger-scale changes to the core project.
Reflections
Another way to think about open source is through the lens of empowerment. You are empowered to see the source code of the software you use. You are empowered to modify it, distribute it, and learn from it. So why not take that to its logical conclusion and empower your community members with the information they need to be productive with and within your open source project?
These are just a few community-focused elements that you might consider through our social model of open source, though they are common to many if not most projects. (There are a few missing elements from our social model that we will address in the subsequent post.)
The next time you are updating the README for your project, review it to see if you are empowering your community with resources that will make them successful, whether as users, contributors, or future co-maintainers.
