Below is a text-based version of the talk I gave at DevXConf 2022. When we write docs for developer tools, we take a snapshot of our understanding of our software, put it into the world, and hope it matches enough of our users’ understanding to make them productive. The wrinkle is that docs are a form of automation. All automation needs exception handling because it can’t handle every possible circumstance. Fortunately, you can build a social system to provide this exception handling for your project. When people help each other get better at using your tools, you’ve got an unbeatable stickiness factor. You want your users to get each other back on the path to success and accomplishment. Developers look for evidence that this is happening before diving into a project. You’ve probably seen this yourself in your own adventures: how much do you weigh the activity of the community of users and contributors when selecting a tool or framework? No one wants to Google a problem and find they’ve become the world’s foremost expert on solving it. Meanwhile, many developers love teaching their peers. It demonstrates mastery and forces clarity in the mental model for how a tool interacts with larger systems. When we run into a problem with our code, we often debug it by searching for error content in Google. If we’re lucky, we’ll find activity from other developers who have hit the same issue. Public debugging processes, with support from peers, creates a paper trail for the bug in places like Stack Overflow or project-specific support forums. A good ecosystem makes it possible to assemble the puzzle pieces to solve problems and get back into action. Community contributors appreciate larger external rewards, like speaking gigs or landing pull requests in popular projects. But initially, they’re helping because it makes them better at the work and it’s satisfying to alleviate shared pain. If you’re stuck in a programming problem, it’s usually because you haven’t met the right people yet. Technical knowledge gaps are actually network gaps.

​
Peer learning levels up your developers

Every new tool has a learning curve. The longer your users are stuck, the more frustrated and discouraged they become. Stay in the red too long, they may move on and try an alternative approach that doesn’t include your project. Conversely, getting unstuck quickly restores them to the satisfaction of flow state, where they feel great because the problems they face are tractable and satisfying. Programming can be high friction. In particular, adopting new technologies presents meaningful barriers to entry, as developers learn new APIs, design patterns and constraints. When we don’t know the solution, but everyone else seems confident, it can create unpleasant feelings of self-doubt. Interrupt this loop—with helpful humans—and you’ve got the basis for loyalty and passion for what you’re building. It’s isolation on the one hand, and relief on the other. These constructive interactions result in real relationships. These relationships result in positive associations with your tool. My friend Dave told me the story of how an early freelance job involving microcontrollers had him stuck in the mud. He found an IRC channel, asked questions, and found an expert who promised “we will figure this out.” They went back and forth for weeks. Dave was in Brazil, his new friend was in Austria, and by the end, Dave was being tempted to consider an AV job at an Austrian opera company. His relationship to microcontrollers was changed forever. Your team can create these positive associations. Early career developers who receive help from staff or project leads are especially impacted. These investments show folks that they are worthy and valued. As a young bootcamp grad once told me, receiving help from a project team member “was the first time [he] felt like part of the developer community.”

​
When you level up your developers, your business wins

When people feel like your tool gives them superpowers, they’re going to talk about that. The best marketing campaign in the world pales in comparison to the power of word of mouth and grass roots support. Imagine what you could accomplish if your users did things like:
  • Blog about how they use your product
  • Publish tutorials
  • Help others navigate known issues your team hasn’t patched yet
  • Start consultancies selling their expertise in your product
  • Lobby their managers to let them use your product on the job
What competitive advantages would be conferred? A healthy peer learning community de-risks the decision to adopt your technology on a scale that’s difficult for you to replicate with your team alone.

​
You can have this!

Let’s talk about what it takes. First, understand that a healthy peer learning community requires balancing opposing needs and scarce resources. You need to serve both askers and helpers, who have different incentives. You need strangers to show up and be constructive, in consistent ways. You’re going to be managing an economy of social capital with volunteers who don’t all want the same things. Every successful technical community has invested countless hours resolving these challenges. They’re hard, but solvable.

​
Define your parameters

Understand the purpose of this space. This is not a social watering hole. I know, I just mentioned the international friendship opportunities of a successful microcontroller community. I’m sure you want that too! But there’s a catch. It’s too common for developer engagement teams to reach directly for friendships and good vibes without first building the foundations that make those things possible over distance: shared accomplishment. Going through something hard lets you really know and trust someone. If you want meaningful relationships, set people up to win real triumphs together. What you want to build is a place for your users to become more sophisticated technologists. You want a place where people can get answers to “how do I…?” questions. Finally, you want a place for maintainers and your formal team to jump in when there are high leverage opportunities to create impact. You can learn a lot about how people are using your tools just by maintaining conversation with them, and these inputs can feed into more formal processes, like pitching a project evolution in your GitHub repo. This is also a venue for your team to create super-supporters. Remember: a little attention from your experts can go a long way.

​
Choose your software

While it can be tempting to spin up a number of peer support channels to stir up as much engagement as possible, I recommend against that. Don’t spread your team and community too thin, especially in your project’s early days. Think about the consequences of how your community software is designed. There’s a tradeoff between the fluidity of chat, and the stability and discoverability of forums. They often work well in concert, but decide what to invest in first.

​
What do people want?

Think about the broad personas your peer support community needs to serve. New users will need reliable debugging help, progress toward mastery, and support in their quest to be worthy technical contributors. Power users need access to maintainers, public recognition, and paths to career advancement. Maintainers and team members need a successful project and sustainable use of their time. You don’t want to overwhelm your crew.

​
House rules and social norms

Here are some questions to help you establish guidelines for your community.
  • What level of question is welcome?
  • What are the responsibilities of those giving and receiving help?
  • How can you turn your newbs into helpers?
  • What do you consider off-topic?
  • How do you reward your loyalists and create a sense of progression?
It’s essential to set expectations and maintain norms, or your community may grow into something you won’t want to participate in.

​
Get your team in there

There’s nothing like getting time with people who make your favorite tool. That’s why your team is a seed crystal for values and culture, and the pilot light that ignites sustainable feedback loops. Remember: interaction with you is one of the central rewards for participation. At the same time, your team’s attention is a scarce resource. They have other responsibilities. That’s why it’s going to be essential to keep an eye out for interactions where your team can have the most impact as the community grows. Occasional mentorship of promising contributors, along with discussions that feed into the next iteration of your product, can be valuable investments of scarce attention. Practically speaking, you’ll need to allocate actual time in your team’s schedule to make this possible.

​
This is how you harness your community’s network effects

Your docs and onboarding can’t cover every edge case. They don’t need to. A successful peer support community starts as exception handling, and properly nurtured, grows into a powerful accelerator for everything from user research to marketing. Be thoughtful, put in the time, and take care of your people. The rewards can define your project.