6

Making Your Project Feel Welcoming

In the United States, often, when a family moves into a new neighborhood, there is what’s called a “welcome wagon” to help welcome people to the area. It’s not a literal wagon (at least not here in Doylestown, Ohio). Instead, it’s a group in a community that gets together and provides welcome gifts to someone moving into the area to help them get to know their new neighbors, and vice versa.

The idea of the “welcome wagon” is to help a new neighbor get past the awkwardness of getting to know a new group of people. As adults, it can be challenging to meet and make new friends, so local customs such as the “welcome wagon” help break the ice, so to speak, with the hope of integrating newcomers to the neighborhood into its activities and social circles.

Too often, open source projects look at themselves and say, “why isn’t anyone contributing to my project?” There can be multiple aspects to this, whether being unable to find out how to contribute, feeling intimidated by donating, or thinking they have anything of value to contribute. As with the “welcome wagon” in neighborhoods, good open source projects look to bring in and make the community feel welcome. It might not be a basket of cookies or a casserole as with the “welcome wagon,” but it can be as simple as a thank-you in a pull request, a mention in a release note, or dropping a sticker in the mail to them.

With burnout as the number one challenge faced by open source projects, this chapter will focus on ensuring your project is welcoming to new contributors. We will cover some of the basic things a project should have, how to best support end users, and embracing community-driven collaboration. Specific topics we will focus on include the following:

• Getting your project set up for newcomers
• Supporting end users effectively
• Being where the conversation is

Let’s start with the basics – getting the project set up for newcomers.

Getting your project set up for newcomers

The first part of having a welcoming project is to give the appearance that maintainers want newcomers. That might sound flippant, but too often, it doesn’t appear that way. First impressions are everything in an open source project, and how your project is perceived is gauged by that first impression. Individuals and organizations use, participate, and invest in projects that they perceive to be run well.

Let’s kick things off by looking at the basics of the infrastructure.

Setting up your project infrastructure

When you first come to an open source project, you likely have several expectations.

First, you want to find the code itself. We see most projects these days leverage a service such as GitHub or GitLab, which offer free code hosting services to open source projects. Additionally, there’s the advantage of being close to other open source projects, which can help your project be more naturally discoverable. When you come to a project, the first file you often look for is the README file. If you are looking for guidance on setting up a README file and other governance-related files, review Chapter 6, Making Your Project Feel Welcoming.

However, a good open source project has much more than just a README file; it has different channels for communication. Things to consider include the following:

• Mailing list: Email is always the lowest-common-denominator medium anyone can easily engage with. Mailing lists are ways to hold conversations with other people in a project asynchronously, which lets people who might be in different areas of the world collaborate without having to worry about whether someone is available. Mailing lists also save past messages in archives, which are great ways to track past decisions and conversations and reference them in future discussions. Open source projects generally use services such as Google Groups, groups.io, or GNU Mailman.
• Discussion forums: Many communities will evolve from using mailing lists to using forums, which tend to be more discoverable and have better search capabilities than mailing lists do. They also, at the same time, have more overhead, as community members might have to moderate discussion threads and channels or help coordinate discussions. However, the way that multiple threads can be discussed simultaneously is one nice advantage forums have. Some communities leverage self-hosted or managed-hosting solutions, such as phpBB, Discourse, or vBulletin, which give a high level of control to the project, but can inadvertently create a “walled garden.” Some projects try to get greater visibility using tools such as Reddit or Stack Overflow, where multiple communities converge but do have a degree of separation. The nice part here is the discoverability, but the downside can be the lack of control over the content and service of the project. Each project will have trade-offs to consider.
• Instant communication channels: In the early days of open source, you’d often see project members hang out on IRC channels, which was a great way to not only get quick help on a problem but also meet others in the community and get a sense of the culture and communication style. Over time, we’ve seen open source projects look at other tools such as Slack, Discord, Rocket.Chat, and Mattermost, each providing similar forms of instant communication and community interaction using different platforms and clients.
• Meetings: Whether this is a virtual web conference call or an in-person get-together, these are opportunities for project participants to speak live with one another. I tend to see meetings as the first point of engagement, especially for those contributing on behalf of a larger corporation. Just like with instant communication channels, these meetings are a good way to gauge the culture and communication style of a project.

Not all projects use all of these mediums. Good projects though tend to use a few of them. Here are some good rules of thumb:

• Always look to have at least one asynchronous method of communication that is easily discoverable, such as mailing lists or forums. This not only makes it easier to have people from different time zones collaborate but also those that might contribute during the evenings in a project that collaborates throughout the day. It also builds up a knowledge library, which while in a raw discussion forum, might not be easily discoverable, but at least gets things written down and makes it easier to build documentation or guides later on.
• Set a regular cadence for meetings and try to make sure that there is an option to join virtually. The regular cadence part is key, as on the one hand, this makes it easier for scheduling (that is, everyone knows that we meet on the first Thursday of the month at 12:00 pm GMT), and on the other, keeps touchpoints on the project more regular to help move work forward. We all get busy, but if we know we have a standing meeting to provide an update in, this at least consciously makes us plan for discussions to happen at the meeting (or lets you consciously say, “nothing new to report, let’s skip today’s meeting”).
• Keep any meetings structured while still keeping them casual. Having a formal meeting might give the impression that the meeting is professional, but it can also be viewed as rigid and hard to participate in. However, a meeting with no structure or agenda will suffer low attendance, as people won’t know why to attend. Good meeting practices apply to community meetings – send out agendas ahead of time, adhere to the agenda topics, keep time for open discussion, and share notes and action items afterward.
• Make it clear where to go for what kind of communication. Driving consensus is hard over an instant communication channel while immediate help is hard to come by on a mailing list.

Now that you have a good project infrastructure setup, let’s put out that “welcome mat” and look at how to build a great getting started guide.

Creating a getting started guide

There’s a general ethos amongst those in user experience design circles on the importance of the “first 5 minutes” that a user uses an application. If a user is successful in those first 5 minutes, it’s usually a good sign that they will become a long-term user. On the flip side, if a user isn’t able to be successful in the first 5 minutes, you’ve often lost them. Open source projects are much the same, even with a more developer- and hacker-oriented crowd; if someone can’t figure out how to use the code quickly, they will move on to the next project.

Getting started guides can vary depending on the project and technology. For a command-line tool, using the --help command-line switch or using man should trigger a usage guide. Here’s an example for the asana-cli project (https://github.com/AlJohri/asana-cli):

$ asana --help
Usage: asana [OPTIONS] COMMAND [ARGS]...
  Examples:
  asana list workspaces
  asana list projects --workspace="Personal Projects"
  asana list tasks --workspace="Personal Projects"
    --project="Test"
  asana list sections --workspace="Personal Projects"
    --project="Test"
  asana list tasks --workspace="Personal Projects"
    --project="Test" --section="Column 1"
  asana delete tasks --workspace="Personal Projects"
    --project="Test" --section="Column 1"
  asana mark tasks --workspace="Personal Projects"
    --project="Test" --section="Column 1" --completed
  asana mark tasks --workspace="Personal Projects"
    --project="Test" --section="Column 1" --not-completed
  asana move tasks --workspace="Personal Projects" --from-
    project="Test" --from-section="Column 1"
    --to-section="Column 2"Commands:
Options:
  --help  Show this message and exit.

In this case, the guide connects a few common use cases to the commands used and then the full set of command options available. This is the appropriate level of detail for people used to working with a command-line interface and Asana. It also does a good thing by putting the getting started guide in the flow of working with the tool, meaning that the user has to go nowhere else but the command shell to understand how to use it.

For more complex projects with different use cases, a deeper guide tends to be a better approach. Let’s look at the GET STARTED page for ONNX as an example:

Figure 6.1 – ONNX Get Started page (https://onnx.ai/get-started.html)

This page presumes the user already understands machine learning models and has a model to use with this tool. So, the first task the user sees is getting that model into the right format for the deployment option they choose, because otherwise, the tool isn’t very useful. This is a perfect approach for the audience and is a big part of making sure the user is successful in the first 5 minutes.

We’ve seen from these examples two common themes to have in mind when you create a getting started guide:

• Knowing your users and giving them the right level of education for where they are at. For the asana-cli project, trying to explain project management isn’t very useful, as the user is already well educated on the topic, or else they wouldn't be seeking out a companion tool.
• Focusing on showing user success in the first 5 minutes. From the ONNX example, if the user can get a machine learning model in the ONNX format, they are set up for success.

A getting started guide serves as the digital presence for welcoming people to your project. Still, as people look to engage more profoundly, they will start to connect with maintainers and contributors. How that experience goes is key to someone wanting to continue being involved. Let’s look at some strategies around being welcoming to new contributors.

Being welcoming to new contributors

As we learned in Chapter 1, The Whats and Whys of Open Source, in the early days of free software, generally, software was developed “behind the scenes” with limited end user involvement. There was a multitude of reasons for that, but one was that end users were generally considered not to have the right level of knowledge of the domain or project design to be helpful. We see this carried over to open source projects today occasionally, which can be a deterrent and hurt the later growth of a contributor into a maintainer. We will see more on this in Chapter 7, Growing Contributors to Maintainers.

Contributors are quite often intimidated by a project; a project has people they may not know, people from a different race, culture, gender, or region, or even people that might be high-level experts in a particular domain. Many software engineers have trouble bridging those social dynamics, so being on top of things is a good way to ease that worry.

The hyper project does a great job of this with their contributor’s guide:

Figure 6.2 – Hyper Contributor’s Guide (https://hyper.readthedocs.io/en/latest/contributing.html)

What is great about this is it doesn’t start with the rules and processes – it starts with appreciation. That immediately shows the project is welcoming.

Having the first personal interaction be positive is another key to success. Let’s look at another example in the just-the-docs project of responding to the first pull request from a user (that user being me):

Figure 6.3 – Pull request response (https://github.com/just-the-docs/just-the-docs/pull/726#issuecomment-1063254623)

Here, the project representative is humble at first; the maintainer realizes I contributed nearly 5 months prior and acknowledges that as part of the thank-you. As a contributor, this tells me that they weren’t ignoring me on purpose, just that life got in the way, and they still appreciate my contribution. Secondly, the maintainer replies by asking me to add documentation, but not in the form of, “You obviously didn’t read our contribution guide because otherwise you would have known to do this.” Instead, the maintainer positions it in terms of value (wanting to make sure others know about the new feature) and offers guidance on where to add the documentation. If you read the entire pull request, you’ll see the maintainer continues to help me to make sure the placement and form of the documentation are correct.

You see the themes of “helpfulness” and “humbleness” as attributes of both examples. When I talk with project leaders, I share that leadership in open source is “servant leadership,” meaning the project leaders are there to ensure the community of contributors and users have what they need to be successful. Keeping that mindset toward all contributions, even challenging ones, helps set the right tone on how a project looks at its contributors. More on this in Chapter 8, Dealing with Conflict.

Welcoming is the first step in making a newcomer want to stay around, but to keep someone around, the project must show how they value a newcomer’s contributions. Let’s look at ways to quickly and meaningfully recognize newcomers when they make an impact.

Recognizing newcomers when they make an impact

Newcomers often see contributing to open source as a way to establish their portfolio of work for potential employers, as these code contributions help showcase the skill a developer has. We will dig deeper into this in Chapter 11, Open Source and the Talent Ecosystem, but knowing this, it’s important to recognize contributors for their own career growth in addition to showcasing your project as a welcoming one for newcomers.

Every project has a way to recognize newcomers, even if they have no funds. A simple way is a thank-you in the release notes; here is an example from the just-the-docs project recognizing not only the new feature but also the contributor:

Figure 6.4 – Recognition of contribution in the release notes

What’s nice here is that this becomes searchable within GitHub as me being a contributor and something that I could link back to.

If you have a budget, then there are a few other options you can choose from:

• Sometimes, contributors have a wish list from a site such as Amazon; go find something on there and buy it for them.
• Send them a t-shirt or sticker. If you don’t have any handy, there are many print-on-demand services, such as Spreadshirt, that can create one quickly. More on this in Chapter 12, Marketing for Open Source - Advocacy and Outreach.
• Digital badge services such as Credly are increasingly popular, and setting parameters to recognize contributors with a badge helps give them something to put right on their resume.

We’ve looked at several key pieces and practices in the project setup for newcomers to the project. One big reason people come to a project is to get help, so let’s look at ways to support end users effectively.

Supporting end-users effectively

Open source projects generally aren’t set up to provide the level of support you need for a commercial product and for good reason. First is that just from a staffing point of view, there’s rarely the capacity to dedicate the same level of support. And second, in open source, we see a community model, meaning we users help other users, and sometimes bugs and workarounds are worked out together in the open rather than behind closed doors.

While a project can learn from commercial products on strategies for supporting end users, there are some nuances in doing so in an open source project. Let’s begin by looking at what effective support looks like with one of the first touchpoints an end user has with the project – submitting a new issue.

Managing issues

We talked earlier in this chapter about project infrastructure and in Chapter 5, Governance and Hosting Models, about the importance of a README file to guide newcomers on the governance of a project. One piece of that governance is how to raise issues, and it is also one of the key questions someone will look for an answer to in a project.

Some key attributes of good issue management include the following:

• Making it easy to find out how to submit an issue: Many projects that use GitHub or GitLab will use the default issue tracker for that issue, as users generally know of that part of the tool and there is little friction in getting somebody to submit an issue. If a project goes down the path of using an external issue-tracking tool, the project will want to call that out explicitly in the README, CONTRIBUTING, or SUPPORT file in the project.
• Helping guide a user on how to submit an effective issue: The best way to do this is in the flow of submission; if a project uses GitHub, you can use an issue template (https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository) to both help users self-triage issues into the right bucket (that is, feature request, bug report, and security issue) and make sure the user provides the relevant information for the project to debug (that is, the version used, the operating system or browser used, the exact error message, and the reproducibility steps).
• Having a regular cadence of reviewing issues and communicating that with users: If you use GitHub, there are various GitHub Actions you can use to automate a friendly message that lets a user know this. The key part of this is cadence – even if you aren’t able to provide a resolution to the issue – is simply saying something such as, “Thank you for the issue. We are a bit backlogged at the moment, but will get back soon.” This sets expectations for the user and lets them know that you are listening.
• On the flip side, leaving an issue out there with no new comments or activity for a long period of time sends the message that a project ignores issues: Making sure to be proactive in reviewing stale issues from time to time not only shows the project is actively paying attention but also helps the project prioritize better (a project might even want to look at automation with something such as the Stale Issue GitHub Action at https://github.com/marketplace/actions/close-stale-issues. Even something as simple as marking an issue for a future release makes a difference – the key here is letting the user know the issue has been acknowledged, is considered valuable, and that there is a plan for a resolution.

Having a good issue management process shows end users that you value their feedback and appreciate them as users, but submitting an issue isn’t the only way that end users engage, so let’s look at broader community and developer management strategies.

Community and developer management

As a project grows and many users use the project in various ways, you will see a natural community form around it. This happening is a great thing – and these communities can take on a life of their own (more on that in the next section of this chapter), but it also requires work for the project to manage.

When I use the word “manage,” this isn’t about control but more about support and guidance. Think of the reason people use an open source project in the first place; it solves a problem they have. When the user comes to a project, they are looking to solve that problem, and the role of community and developer management is to be a guide. Good community and developer management has these attributes:

• It recognizes the needs of a user, meaning that it can see the comments and feedback and help roll them back into the project or showcase how to resolve them.
• It’s proactive, meaning it looks to share content and insights as early as possible so that other users don’t have the same struggles.
• It’s embedded into the community by engaging other community members directly, speaking at events, doing meetups, posting videos, and other engagement activities.
• It’s empathic and positive, as good community and developer management takes into account that the users often come to the community out of frustration, and the role of community and developer management is to be understanding, help resolve concerns, and have the user walk away with a positive experience. More on this in Chapter 8, Dealing with Conflict.

A great example of the value of good community and developer management is looking at when Apache Cloudstack and OpenStack were the two predominant open source projects for Infrastructure as a Service (IaaS). Both technologies were fundamentally sound, and each had something that the other didn’t. However, in the end, OpenStack came to be the market leader. Why was that? OpenStack heavily invested in community and developer management, which helped users and developers be more successful quickly, and helped the project itself grow to solve the problems the users had.

While a vibrant community can provide an immense amount of support for an end user, it’s never going to be at the level that commercial support would be. Let’s look at how to best have commercial permission to support end users effectively.

Commercial support

We spoke at the beginning of this section about how open source projects are not set up to offer commercial support, but that doesn’t mean that other companies can’t step in and offer it.

A great example is in the Linux distribution space, where among a vast number of Linux distributions are several that offer commercial support (examples include Canonical, Red Hat, and SUSE). Each of these distributions is offered for free or has a free offering, but at the same time, they can provide the level of commercial support that a larger company would require. After all, not many open source project maintainers want to be fixing bugs at 11:00 P.M. on Christmas Eve.

We see more formal models of this in other projects. The Kubernetes Certified Support Provider (KCSP) program (https://www.cncf.io/certification/kcsp/) provides a mechanism for vendors to indicate that they offer commercial support for Kubernetes. What’s nice about this program is it’s not run by any one vendor, but by the Kubernetes community itself, so end users have an unbiased and objective view of the service providers, knowing that the community sets objective standards around training, business models, experience, and upstream support. This program in particular requires vendors to be members of the Cloud Native Computing Foundation (CNCF), which means some of the revenue they take in from support is funneled right back into the project for infrastructure, events, and community support.

A key takeaway is that commercial organizations getting involved in an open source project is a good thing, just as we discussed in Chapter 4, Aligning the Business Value of Open Source for Your Employer. As described in Chapter 5, Governance and Hosting Models, good governance helps ensure vendor neutrality for a more collaborative project.

We’ve looked at some strategies for supporting end users in your project’s community. What we often see in vibrant communities is that the community starts to form new spaces for collaboration, which can be helpful for the project but also does require some degree of management from the project. Let’s look at this now.

Being where the conversation is

Nearly all the best things that came to me in life have been unexpected, unplanned by me.

– Carl Sandburg

Open source communities are not something you can completely design. Indeed, you can provide infrastructure, support, and guidance, as we’ve spoken about in this chapter, but the magic of them is when they take on a life of their own. When I was a community manager at SugarCRM, I remember always being amazed and delighted at the interesting extensions that the community members built and the motivations behind them. Linus Torvalds did an interview a few years back, and when asked about what was surprising about Linux development, he said the following:

“What I find interesting is code that I thought was stable continually gets improved. There are things we haven’t touched for many years, then someone comes along and improves them or makes bug reports in something I thought no one used. We have new hardware, new features that are developed, but after 25 years, we still have old, very basic things that people care about and still improve.”

(Source: https://www.linux.com/news/linus-torvalds-explains-how-linux-still-surprises-and-motivates-him/)

We often see virtual collaboration as the first channel to take off for communities, so let’s look at how to best manage online forums and social media.

Online forums and social channels

As we’ve seen technologists and open source enthusiasts grow in their careers, you tend to see them congregate in different online communities. Back in the early days of open source, we saw platforms such as Slashdot as the center of gravity, and over time, newer platforms such as Reddit, Stack Overflow, and Hacker News have become the center point for these discussions. Add to that the growth of social media and it can mean your project can be talked about all over, but it might be hard to stay on top of the conversation.

Some projects become concerned about conversations regarding their project for so many reasons, but I’d argue to embrace it. Communities in which collaboration only happens through specific forums or mailing lists can become an unintended “walled garden.” But it’s not easy – here are some tips and best practices:

• First is to use the subscription features in Reddit, Stack Overflow, and other platforms to be alerted when your project is mentioned. Other services can track the web more generally, such as Google Alerts. These are great ways to use automation to alert a project about a conversation happening.
• When you find these conversations, promote them! Sharing that someone on Hacker News used your project in an interesting way not only shows appreciation for that person sharing their story but also showcases the project as mainstream.
• Comment in those conversations to connect the author of the comment and the other commenters to areas of your documentation or other blog posts. This helps connect someone who might have stumbled onto that conversation to the right resource. If something isn’t written up, write it up and link it back to that conversation. This helps drive people back into the project but ensures there aren’t loose ends of discussion out there at the same time.
• Post about the project on those online forums and social channels where the discussion is happening. This comes back to what we talked about with good community and developer management – it’s proactive.

One thing I will say from personal experience as a community manager is that managing all these online forums and social channels can be taxing. It’s easy to get caught up in discussions, and before you know it, a full day has gone by. Think about smart engagement and management; one tip I would share is to limit how much time you spend on this in a given day/week and try to stick to that. It’s okay if you miss a post out there; what I have found out is that on the online forums and social channels, you see the participants starting to do the work for you.

Community members often start with virtual engagement and then move to more direct engagement with peers in the community. Let’s look at the role of regional meetups and events.

Regional meetups and events

Meetups and events are a large part of the open source culture. They are also crucial for sparking collaboration. If there is one thing I’ve seen as we’ve emerged out of the COVID-19 pandemic and started to be a part of in-person events again is that face-to-face interactions spark innovation and collaboration. Online collaboration can provide some of this, but it’s so much more natural and organic in person.

Having your project be part of events such as these is an easy way to increase its visibility:

• First of all, give talks at conferences. Larger conferences can be harder to break into as a new speaker, but smaller regional events or meetups always look for new topics and speakers. Some of these events also provide travel funding or stipends to offset costs, which can be helpful if the project isn’t sponsored or supported by your employer.
• When you are at a conference, don’t sit in the corner with your computer hacking away at your project. Go up to people and meet them. Attend sessions of interest, speak with the speaker afterward to learn about the work they are doing, and see whether there are ways to work together or maybe get some advice. This organic conversation is better known as the “hallway track”, and is where so many interesting ideas start.
• If your session is recorded, share it in your community or via your social channels. If not, share the slide deck and write up the event. This shows a connection to both the event, its community, and your project’s community as well. Plus, it also gets that content to a wider audience.

Communities from digital and in-person collaboration start to gravitate around natural leaders and influencers and having a project recognize them helps motivate the person and guide the society toward them.

Being supportive of the community taking on a life of its own is a validation of the value of the open source project. That doesn’t mean it’s always easy, and we will dig more into this in Chapter 8, Dealing with Conflict.

Summary

This chapter covered several aspects of making your project feel welcoming, including having a good project infrastructure, a positive and inclusive culture in bringing in end users, and enabling the larger community to showcase the project in new areas and drive collaboration in different arenas. We scratched the surface of community management, and there are entire books out there that go deeper into the topic, which would be great reads if you have more interest in this area.

A key aspect of making newcomers feel welcome is supporting them in becoming contributors and maintainers over time. Let’s look at this in more detail in our next chapter, Chapter 7, Growing Contributors to Maintainers, and see how to help contributors make that transition.