Polite Technology First Draft

This is a preview of Polite Technology: sign up to get an update once it's finished:

Polite Technology

In software and especially in open source software, so-called "people skills" are underemphasized.

This is a book about the social interactions and situations that are the underpinnings of the open source world. It's about how humans collaboratively create software.

Specifically this is about creating open source software. Open source software, loosely defined, is software that is free to share. Open source software is released under a license that reverse-engineers copyright in order to protect this right to share, instead of doing copyright's traditional work of restricting sharing.

The ramifications of this tweak to copyright are tremendous. Open source software doesn't have to be a closely-guarded secret: instead, it's usually created in public spaces, shared widely, and distributed for free. Because everyone can read the source code and contribute changes back, software projects can become collaborative projects between multiple companies, private individuals, foundations, and even governments, all sharing in the work of creating software and the benefit of having it.

The successes of open source software have been world-changing: the Linux operating system runs most of the Internet, the git version control system is the basis for GitHub, and thousands of other pieces of open source software make everyday life possible. On a personal level, open source software and the systems of collaboration it comes with have enabled people to work remotely, make friends, and learn about parts of systems that were previously the exclusive domain of experts.

But that's the ideal. The everyday work of creating things is difficult and fraught - filled with the same social difficulties as any other job, as well as unusual new challenges. How do communities scale when they contain differing opinions and styles? How do decisions get made without formal power structures - or does decision-making require the creation of such structures? What about the way that these projects interact with companies who wield the power of commerce, users who have the power of speech, and developers who may have more technical skill than collaborative ability?

The world of technology is filled with fascinating technical challenges and big esteem boosts for whoever can factor primes faster or reduce latency. But people problems are the ones that decide whether most projects succeed or fail. Software projects are made of people with priorities, feelings, and needs. The daily tasks of a project maintainer often have nothing to do with typing C++ and lots to do with resolving conflict and balancing concerns.

That's what this short book is about. We'll discuss some common situations and the tricks you can use to handle them, as well as larger problems that have no clear answer. Thinking hard about non-technical problems has made me a better participant in open source, and I hope these ideas can help you as well.

Table of Contents

Brief sidenote about culture

The social situations we're going to discuss are all relative to who you are, where you are, and who you interact with. I can observe other people's lives, but I have only one, and that is the life of someone who is generally on the top of the bell curve of the technology-industry demographic: an American white man in his late 20s.

This is relevant. Emotional labor is a useful concept for understanding this area of life: in certain job roles, there are expectations about another person's emotions and tone. In America, baristas are usually expected to be bright and cheerful. Bartenders should be friendly and familiar. And these expectations are typically gendered: outwardly showing that you're having a bad day when you're a woman is different than when you're a man.

Some of the techniques covered in this book may seem old-hat. Others may be a major adjustment. We're trying to establish best practices: tried and true techniques for dealing with a variety of situations in ways that agree with many types of people.

A brief introduction to me

Hi, I'm Tom. I've worked on many open source projects over the span of over ten years. Some projects have taken off and acquired a life of their own. Others have failed. Some have thousands of users and lots of contributors, others have produced software with hundreds of thousands of users and almost nobody writing code.

This short book is taken from my experiences in this field, research, and observations of many projects and communities coming and going throughout the years.

Programming has a persistent focus on the craft: the craft of writing code, of programming and understanding technology and techniques. But technically brilliant people can't survive alone. People who can build communities and work productively with other people can be more successful than those with supernatural coding skills.

Lingo

Reporting bugs

If you use software, you'll encounter bugs. Sometimes software does the wrong thing, or doesn't anticipate what you want to do with it.

With open source software, it's easy to write to the software developers who write applications and libraries. But communication is an art, more than ever. A good bug report includes the right information, in the right place, and with the right tone. Here are some tips for how to write a bug report that will make both you and a software developer happy.

This bug report for GitLab.org is perfect: it gives specific steps to reproduce the issue and says exactly what behavior was expected and what behavior occurred. In this guide, we'll walk step by step, through the things you need to say in a bug report.

Be nice

Software developers are people too.

Maybe the bug ate your homework, or it's taken you hours to track down the culprit and the bug is something really silly, something that nobody would ever do. It's okay to be personally annoyed, but don't take your anger out on another person: nobody deserves abuse.

Many open source projects have adopted a Code of Conduct to make their norms, rules, and responsibilities explicit. If a project uses a code of conduct, review it first before drafting your first message.

And while a bug may be critical or preventing you from finishing a project, it's not useful or appropriate to insist a developer prioritize it. They may have other issues that are far more important, whether professional or personal. If an issue is truly urgent, you may want to hire someone to fix it, or try to fix it yourself.

Describe your configuration

Sometimes software works in one place, for one person, but doesn't somewhere else. Your operating system, browser, and other installed software all has some impact on the bugs that crop up.

Include basic information about your setup to make issues easier to debug. If it's a web-based application, include:

For installed software and libraries, there are some other things to report:

If it's a web application, you can be extra nice by opening up your browser debugging tools, seeing if there's an error in the Console, and reporting it exactly, by copying & pasting the text.

Provide an example

If you find a bug in a library, like a jQuery plugin or kind of module you use in your own software, try to provide a minimal example or test case that demonstrates the bug.

You can create a GitHub Gist to share a longer code snippet, or if your bug is best demonstrated with live HTML, JavaScript, and CSS, services like JSFiddle and codepen make it possible to create an example that actually runs on the web.

The key to creating examples is making them as small and focused as possible. Isolate the bug's behavior from any other code and technology in your application so that it's immediately clear what the issue is and maintainers can quickly run the example.

Specifically say what is wrong

It's broken...

When you report a bug, it's because something is wrong. Writing simply that software is 'broken' or 'crashes' doesn't give a software developer enough information to fix it. A great bug report specifically says what you tried to do, what you expected, and what the software did instead.

I added 2 + 2 in my calculator.

I expected it to give me a result of 4.

Instead, it gives 5.

"It Crashes" is not a good bug report: it's like telling a doctor "it hurts" without specifying how, when, or where.

Crashes have many distinct varieties that you can distinguish by using more and better words. For instance, "the browser tab crashes with a sad face icon" or "the browser tab becomes unresponsive" or "my computer crashes". Descriptions like these, that replace the ambiguous "it" and use a more specific word than "crashes", help get issues fixed.

Use a bug tracker

If the project has a bug tracker, like GitHub issues, JIRA, or Phabricator, report the bug there, and there alone. Developers will be notified and respond.

If you aren't sure that what you're seeing is a bug, don't ask whether something should be working or should be broken - just report it in full, and the developer will follow up with clarifications.

Search for & subscribe to existing issues

Search the bug tracker first for the issue you're going to report. Active projects will often have a long discussion already started about exactly the issue you're running into.

When you find an issue, the first thing you should do is to click the subscribe button. This will subscribe you to the thread, triggering email updates when someone posts back to it. Never post +1, 'Any progress?' or other sorts of pressuring comments to threads.

Responding to bug reports

If you haven't given up the dream of writing bug-free software, I suggest you do so now. Accepting that all things are flawed will make bug reports feel like a blessing, not a curse, and will alleviate some of the stress they can cause.

Now let's get in to bug reports.

If you're lucky, the person reporting a bug has read the polite.technology guide. But in most cases, sadly, they won't have, and that leaves you with a few predictable cases:

Asking for clarification

Bug reports and, in fact any sort of support work, involves a lot of clarification.

Setup matters. The difference between a warning and an error, between Internet Explorer 8 and 10, is vast for a developer: knowing a person's browser and the quirks of their setup will immediately give a few clues for the cause.

You need to know, precisely, what's the problem. Most bug reports lack detail of what's going wrong: does broken mean that the screen is blank, or that something is rendered slightly incorrectly?

It's wise to get clear answers first, rather than guessing about the user's setup or the problem they're encountering. Here's an example script:

User:

I've installed your software and it's totally broken.

Developer:

Thanks for the bug report! To make this easier for me to diagnose, could you please say more about what browser you're using, what you are trying to do, what you expect the library to do, and what happens instead? If possible, provide a JSFiddle or include some of your relevant code - that would make this problem much easier to pin down.

Closing duplicate and irrelevant issues

Duplicate issues are a fact of life: even people who search for existing issues often can't find them because they'll use different words. But being the maintainer, you will likely have a mental list of all the popular issues, and have to close the same recurring issues repeatedly.

When this happens, resist the impulse to be short, and instead follow this friendlier script:

Instead of:

Duplicate #342

Try:

Hi Jane!

Thanks for posting this issue! It's a valid concern, and we're already tracking it in a previous issue, #342. I'm going to close your issue now to keep the discussion in one place. If you have any further input on the main issue, #342, please post it there.

Thanks!

Why Reporting Bugs is So Hard

Why is reporting a bug so hard that it justifies so many words?

Software is fragile.

Your Honda Civic might run for a hundred miles with the oil light on. A piece of tape will keep your headphone table working even when it starts to fray. Humans relentlessly keep living despite sickness.

Software is fragile. Forgetting to type a single character breaks an entire system.

Software has multiple levels of fragility. The applications you use are released under some corporation's name - Apple, Adobe, Microsoft - but are built on the work of thousands of others. They inherit bugs from the languages they're written in. They can inherit bugs from the operating system you use. Or bugs in other systems that they talk to, like servers or other devices.

So reporting bugs is hard because there are so many potential causes for any specific bug. Many bugs are only triggered after a specific series of actions, some of which might be mistakes on the part of the user.

Regardless of the cause, the fundamental problem with most bug reporting is a lack of clear communication.

Creating rules

Open source projects with ground rules tend to be more successful than those that operate ad-hoc. Rules are mutually-understood principles that are usually set in English or code. Examples of rules include:

Why create rules?

In the case of automated tests and code style checks, turning your preferences into automated rules saves you time. Poorly-written or incorrect code doesn't require a detailed code-review - instead, you can point to the explanatory errors given by the test suite or style checker.

Codes of Conduct are cultural rules.

You need to moderate the community that forms around your open source project, and having a Code of Conduct gives you consistency and predictability: by reading the CoC, a member of the community will be able to know what kind of behavior is appropriate, and what the consequences of inappropriate behavior are.

Over the past 10 years, open source licenses have become very liberal. New licenses like the BSD license permit a lot of different uses and adaptations: if you use this kind of license, a company can integrate it into their software and sell that software, or redistribute a modified version of it. But licenses have limits: usually they require some form of credit. And even this minimal requirement is often ignored or knowingly broken, and in these cases, choosing a specific license gives you legal recourse.

If you don't know which license or code of conduct to use, here are two good defaults:

Contributing.md

A contributing file is an overview guide for how to contribute to an open source project. If you're using GitHub, creating a file called CONTRIBUTING.md will cause that file to appear at the top of the issue tracker whenever anyone starts to create an issue.

Nadia Eghbal's Contributing Template is an excellent place to start for creating a CONTRIBUTING.md file.

Issue Template

If you're using GitHub to run your project, you're likely also using their issue tracker - a simple system for people to report bugs or request features. Compared to most issue trackers, GitHub's issue tracker is freeform: an issue is anything with a title and a free-text body.

Luckily, GitHub introduced issue templates: files that you can include in your repository to pre-fill issues for people. This lets you add lists and other kinds of required structure to encourage people to follow useful patterns.

Open Source Templates is a crazy but super useful "choose your own adventure" style website that provides a range of different issue templates geared to different kinds of open source projects.

Intent and time commitment

Before you create that new repository, write the tweet, or start googling for the best new functional programming framework, take a moment to reflect.

You're probably building this software because you want to. You want to build it because you have a need, something that doesn't exist in the world, or just an itch to scratch so that you can learn something new.

Consequences of building a thing you can't maintain, don't need, or duplicates an existing effort

The worst case is that you waste your time and end up with a new responsibility. You might only have a few users, but even their costs will add up.

The advance of the technology ecosystem creates inherent maintenance costs, even if you write bug-free software.

Keep in mind that software maintenance costs aren't only caused by engineering mistakes or new requirements: the world will shift around your software. You'll write a JavaScript library and it'll break in the next version of Node.js. Or a Python version and it'll work in Python 3, but not in Python 4. You start with a perfect, modern library, and soon you'll have something that no longer runs on any modern computers. This is the reality of technology.

If you're writing code for the sake of learning, accept it as that

Because the next section will be about not reinventing the wheel, let me preface it by saying that sometimes it's a great idea to reinvent the wheel. Lots of big improvements in fundamental systems have been created by people who simply wrote what they thought it should be, without consulting the prior art. And implementing basic software gives you valuable experience that you can't get if you only use it or build on top of it.

Help projects attain critical mass

Most open source projects are the work of one contributor. One person has the problem, solves it, publishes the code, and attracts a few users. Sometimes they attract a crowd of users. As we'll discuss in Nurturing Contributors, growing a project from one contributor to two or more is the central struggle of open source.

When you create a new project that tries to do better than an old one, you decide not to increase the contributor base of the old project. Your contributions could have been the thing that gets that project over the hump, and the maintainer might have been planning on implementing something really similar but never got the time, and would have been overjoyed to accept you.

This isn't meant to be a guilt-trip. Sometimes you need to create a new project, even if there's an existing one. The maintainer might not accept pull requests, or might have a big difference of opinion. You might be trying to learn.

But if your goal is to make the most impact, contributing to an existing project can be more effective than creating something new.

The Buyer / Seller Relationship

Economically, we tend to think of sellers & buyers, customers & businesses, exchanges of value. Physical goods have per-unit costs that often make up a large part of the total cost of production. Even with the sunk costs of the factory finished, there's a big difference between building one car and building two.

Software doesn't have this attribute: the cost of distributing and copying digital works is usually too low to measure. Usually when people realize this, the reaction is joy - a hope for utopia. In the world of software, a few people can indeed make an outsized impact on the world. An iPhone game can make millions of dollars without requiring a factory or a team of salespeople.

But much like any product, the "parts cost" of open source is only a fraction of its actual cost to produce. Bandwidth can be free and distributing copies of the software can be instantaneous, but the marginal cost of each unit is dominated by two other costs: support and maintenance.

Support

A lot of this book is devoted to kinds of support. Whether it's an IRC channel, an email, an issue tracker, a conference, or any other form of community, much of what happens in open source is support work. Whether it's helping people understand documentation, helping people who don't read documentation, giving advice about how to solve new problems, or diagnosing potential bugs, this is support work.

And it's likely that very early in a project's history, the time you dedicate to support will outweigh the time you spend writing code. Your software-writing time scales with the complexity of the project: your support time scales with the number of users and contributors you attract to the project. Very successful projects with thousands of users quickly accumulate hundreds of support issues.

Expectations

Acquiring open source software usually doesn't involve any payment. There's no contract between you and your users, or between you and the people whose software you use.

But the buyer/seller relationship we have in everyday life automatically carries over into this world. People have expectations that software will work, that issues with software will quickly be fixed, and that you'll answer their questions.

This relationship is often the hardest part of software because it as some similarity with traditional buyer / seller relationships but substantial and important differences. With no payment or contract, you can't give an angry user a refund. You can't suggest they leave your store. You'll naturally be in the most empowered place to make the improvements your users want, but how are their needs expressed and received?

Of course, financial transactions aren't the only kind of value exchange. You might work on features in order to make your projects more popular, which leads to a better portfolio and reputation in the community. Reputation can lead to a better job or better positioning if you found a company. You might work on a feature in order to learn about the problem or acquire new skills.

There's no easy solution to this problem. BountySource is one potential route. It's a website that pools money and uses it to pay contributors to an open source project. Big projects like neovim with thousands of users but a relatively smaller developer group have successfully used BountySource to pay people for their time, so that developers are motivated and compensated to work on things that benefit lots of users but aren't necessarily fun, educational, or useful for building reputation.

Being successful

The next section, about maintaining software, presumes that you have software to maintain and users to respond to. In other words, it assumes you have a project with some degree of success.

Let's discuss success.

You probably have a few definitions about success from the rest of your life. Success might be making connections, helping others, learning, self-expression, earning respect, or something else entirely. In the context of software, your goals will probably be pretty similar. Our driving reasons are usually deep-seated and take a long time to change.

Gamified indicators tell a simple story

If you look at a site like GitHub, it is gamified in some obvious ways:

Gamifying something means that you simplify it, just like any representation will simplify the actual experience. It isn't GitHub's fault that they can't capture success in a number: nobody can.

These gamified elements might line up with the things that make you feel happy and accomplished, or they might not. Don't mold yourself to fit them. There are lots of important and impactful projects that don't fit the gamified criteria: projects that have influenced shifts in technology but don't attract much attention, projects that have more social and interpersonal benefit than they have downloads on GitHub or npm.

Keys to success

We won't cover luck.

Experience

Building great software usually requires experience: there's a big gap between academically or theoretically good ideas and things that work in reality. In other words, it's unlikely you'll hit a home run on your first try.

There are two ways to get experience: contributing to other people's projects and rewriting your own. You should do some of both. Established projects have learned some lessons, tend to have processes in place, and when they've made mistakes, have explained and started to understand how they happened.

Rewriting your own projects is also important. Just like drafting English, your best work is often in the second or third draft. And until your projects have lots of users, the disruption caused by gigantic shifts is negligible.

Communicating clearly

Popularizing open source projects is very similar to advertising and selling a project. Some open source projects even have logos and websites that are higher-quality than the closed-source or SaaS alternative.

But don't overthink communicating or 'branding' your project, the most important thing, the one thing that you cannot do without, that so many people mess up is simply a sentence that clearly describes what it is and what it does. Getting that written gets you most of the way there.

Defining the problem

Usually someone will include 'keep it simple' on the list of factors for success. I don't think this is a very useful framing of the issue: rarely do people, even novices, aim for complexity. Instead, they tend to overcommit on what the project should be and what it should do, and the extra complexity is necessary to fit the expanded idea.

Keeping your idea for the project small enough to accomplish is key: this is scoping, and it's often something that a product manager will do. If you don't have a product manager, and even if you do, scoping is part of your job as a programmer. Detect and deflect additions to the scope that will make your project too complex for you to maintain and perfect.

Genial voice

Hi Reader!

Email is traditionally the only medium where both greetings and a signature is still expected. Text messages, for instance, rarely begin with "Hello Julia, I hope you're having a great day", unless they come from your parents. The same goes for GitHub tickets: maybe because there's always a username and an avatar on the top, it's rare to see actual greetings and email-style communication style.

This makes the genial voice a sort of cheat-code for improving communications. Write in the genial voice using people's first names and friendly introductions and you might be perceived as a square, but more often than not, people's responses are friendlier. Sometimes people will even follow your lead and respond in the same style.

Technically, the genial voice makes your signals of friendliness redundant - the friendly greeting and goodbye will benefit from the serial position effect and stay in someone's memory, giving you a better impression on average.

Rejecting pull requests

Contributions are a wonderful thing: waking up to someone liking your work and deciding that they want to help build a project is a great feeling.

Many contributions are easy to judge: someone fixes an issue or adds a feature that's clearly within the scope of the project and all you have to do is a round or two of code review and the contribution is in. Saying yes to contributions is easy and satisfying.

Let's talk about saying no.

Why say no to someone who just spent their own time trying to help you? It's a common rookie mistake to never say no - to allow everyone collectively to guide the scope of your project and accept changes with little hesitation. But any amount of time as a maintainer and project manager will make you aware of the importance of keeping a tight scope. And if you spend time reading contributions, you'll find that most of them have issues, some of which cannot be resolved.

Here are some pull requests that I've personally had to reject:

Rejection is hard. There are a few key things you can communicate to soften the blow. Like many of the other things I recommend, the underlying strategy is that you need to be explicit about the positive and emotional parts of an encounter, not just the technical parts. It's simple and easy to deliver a code review, but implicit in that review is the fact that someone took the time to contribute, and that should be recognized as well.

Always begin with thanks

When someone contributes to open source, or helps anyone else, they're giving their time willingly to support others. They could have kept a private fork, or kept to themselves, but instead they chose to be helpful.

So even if a contribution has quality issues or is something you completely disagree with, say thanks. For instance:

Hi Suzie,

Thanks for opening this pull request!

Note that this is using Genial Voice: see the chapter on Genial Voice for an explanation of how & why.

Acknowledge needs as valid

Take the example of porting a project from one language to another. In my case, it was from JavaScript to CoffeeScript - languages with a sometimes-antagonistic relationship.1 CoffeeScript fans believe the language is simpler, JavaScript fans believe their language is more direct. The delivery of CoffeeScript PRs often comes with a mission statement that reflects that divide. Similarly with pull requests to add Bower support to JavaScript modules that work in the browser - the Bower & NPM communities are somewhat ideologically divided.

Interactions around these contributions can fall into the trap of reflecting the community arguments. You can avoid this with a simple trick: acknowledging needs as valid.

When someone contributes a patch, it's because they have some need. Simply say that you acknowledge that needs, and you're instantly in a much better place:

Thanks for the contribution! I appreciate the effort to make this project more accessible by porting it to CoffeeScript, and it's very cool to see it in this language. I'd like to keep it in JavaScript, though, because that's the language I'm comfortable with.

Present the ways out

Rejected pull requests aren't a dead end, so don't make them sound like the end. You should encourage everyone to contribute again, and present their options explicitly:

I'm going to close this pull request, but I hope you can contribute in the future! If you need this change, feel free to maintain a fork.

Maintaining open source software

Let's talk about everything except for software development. Sometimes the image of a software developer is a person typing, alone, all day long. In most cases, programming consumes less than half your actual work time, even if that's your job description. Some of that is hated busy-work, some of it is social interaction that keeps you sane, some of it is akin to emotional labor.

Technology changes and every project is unique but there are common components to this work, like interacting with people, supporting and critiquing the work of others, and explaining your craft.

Let's find the parts in common and pick ways of expressing them that are both productive and kind.

Automating emotional labor

If you've read a section with an example script - an example of what you should say to be extremely nice in response to some situation - you'll notice that the nice version is usually a lot longer than the default. You can type "Duplicate #142" really quickly, but not something like:

Thanks for posting this issue! It's a valid concern, and we're already tracking it in a previous issue, #342. I'm going to close your issue now to keep the discussion in one place. If you have any further input on the main issue, #342, please post it there.

Here it's a good idea to steal a trick from professional customer support teams: use snippets. Software like TypeItForMe and TextExpander let you type short abbreviations like ;close, which expand to long pieces of prewritten text - and even support token replacement, so you can replace custom parts of the text, like the issue number.

For a comic perspective on emotional labor, check out the emotional labor Chrome extension. What I'm talking about here is the social expectation for people to show warmth or cheeriness in certain situations or professions - like the American expectation that baristas should smile.

Responding to feature requests

Once a project achieves a certain level of success, it will have users, and those users will have additional demands of the project in the form of feature requests. Experienced and empathetic users will state their feature requests precisely and kindly, but others will use an unfriendly tone or imprecise language that doesn't lend itself to a solution.

  1. The maintainer does not owe their time to anyone
  2. The maintainer must treat everyone with respect

Ignoring the first principle will lead to burnout: there are unlimited features to be requested and limited time to implement them. The sense of obligation quickly becomes an emotional burden.

Ignoring the second principle will damage the project and reduce its chances of ever attracting additional contributors, which is the only way to succeed in the long term.

  1. Maintainers are the keepers of the project principles
  2. The goal of the software.
  3. The scope that defines problems that the software will try to fix and those it will not.
  4. The style of the project: which programming practices are used, which language.
  5. The culture by which the project is managed.
  6. Maintainers approve of changes to the software by these principles, and also manage discourse and which other contributors are allowed.

When will this be done?

People often ask for estimates - when will a bug be fixed, when will a feature be implemented? This is totally reasonable from their side, because they might be waiting for a bugfix to launch a product. Lots of people asking you for estimates at the same time can be overwhelming and seem like overstepping, but you don't need to take out your frustration on each one of them: instead you can use a form response:

I'm working on it right now, but I'd happily accept a Pull Request to speed this up. This is a relatively big project, with lots of work to do, and we could really use more contributors!

Or:

Unfortunately I'm quite busy right now and I don't know when I'll get the time to finish this. I'll happily accept a Pull Request to implement this feature if you can find the time to do it yourself!

Acknowledging concerns as valid

A common thread between successful ways to respond to bug reports, feature requests, and communications in general is to acknowledge concerns as valid. This can be tricky, because often people will immediately present a concern, a potential solution, their emotions, and other signals, all at the same time. It's important to read carefully to observe each element and respond to each element carefully, rather than discounting or accepting statements in their totality.

For instance, let's say that you have a user who is interacting with your JavaScript library, and they call a function that expects text as an argument but they provide it with a number. After hours of struggling with this problem and cursing your library and everything else, they realize this problem and write an impassioned ticket:

Ugh, well you just wasted ten hours of my time. Why is this library so strict about the types of data it accepts? Can't you just convert everything to strings - that's probably quick to do.

You get this ticket at 8 in the morning on a Monday, and the signals cross:

So you have multiple signals, and multiple options for how to respond to and categorize them. Should you hastily close the ticket and insist that they need to read the documentation? Make it clear that your time isn't theirs, and changing your library would be a terrible idea?

Probably not - that would only escalate the conflict, making a frustrated person even more frustrated.

Here's a vital script to follow:

I see that this cost you a bunch of time. I understand that this was confusing to debug and the library didn't work the way you expected it to. I'm sorry that it was such a tough time.

The gist is simple:

Moderating discussions

As the maintainer of a project, you can guide conversations and keep them civil and productive, and take action when they aren't.

Un-derailing

A conversation is derailed when it starts out as a friendly exchange but becomes focused on other issues or loses its civility.

You can initially try to keep a discussion on topic by re-asking or re-stating the original post in different words. People who discover the thread will read your on-topic comment and get back on topic.

If the discussion touches on a new, but different, topic, encourage participants to create another thread, so that the original thread can stay focused.

Moderating tough conversations

Just like politics, it's best to exhaust the diplomatic options before considering the rest.

Make sure you understand what someone is angry about. Ask questions about what's wrong and what could be improved. Showing interest make the person feel heard, and often the actual problem at stake is different from what it first appears to be, and can be easier to solve. The X-Y problem describes one of these cases, and is a great read. Entire wars can be fought based on misunderstandings: asking clarifying questions is a good idea.

Disagreements with collaborators call for more time investment and a different approach: one of the best options to is to get on a phone, video chat, or meet in person. Seeing emotional cues makes conversations easier, and a lot of times meeting in person will reveal the background of why someone is feeling a certain way and saying things. It seems to you that they're being opinionated and reckless, but maybe they have to hit a deadline for work and have a baby to take care of.

If you can, face problems one-on-one at first, whether it's via chat, email, or in person. The privacy of a personal conversation makes people less defensive and more amenable to change, and also ensures that you don't 'make an example' of someone and establish a pattern of fighting in a community.

If social means fail, a GitHub issue tracker gives you several levels of control:

Your space to moderate

There are multiple ways of seeing your project. Is it a free space with you as the de-facto leader? Do you fight for people's right to say anything within legal boundaries, or are you an active moderator? What is your responsibility to create a caring community?

One opinion is well-summarized by Anil Dash: moderation is part of running a community of any kind. Active moderation has a good track record.

While the shape of your community won't be a perfect reflection of its rules, there is some degree of correspondence with the presence and type of Code of Conduct you choose, assuming you choose one.

For instance, The Contributor Covenant mentions:

It doesn't simply say "don't troll", and it goes far beyond what's legal or illegal. The rules themselves specifically call for a positive environment, not just a safe one.

Nurturing contributors

Building a larger contributor base is one of the most important and most difficult goals of open source software. With four or five people working on a project and taking ownership of its success, you have a more resilient project, more ideas in the mix, and greatly reduced stress.

But establishing that size of a contributor pool can be difficult: while bug reports flow in, Pull Requests are rarer and usually fix a specific problem that a user is running into. And the combination of free time and motivation required for open source work can be hard to come by, when everyone has day jobs and other priorities.

So contributions are valuable and contributors are amazing, and you should praise and hang on to them.

Building contributor skills

  1. Guide and teach people by giving great code reviews
  2. When you set a policy for contributing to your project, like requiring a pull request for each feature, follow it yourself. Show the thinking behind your changes.

Building contributor enthusiasm

People who start contributing to open source usually have a grain of enthusiasm already. Your job as the existing contributor is to nurture that bit of enthusiasm into something bigger.

Here's an example of an especially friendly thank-you:

Thanks so much for this PR! It's such a big lift for this project and I really appreciate you taking the time to make it. Hope to see you around!

Providing support

All successful projects will require supporting users, regardless of how much documentation is provided. Really successful projects can include a lot of support work - enough that companies can make a business out of answering support emails and calls.

You might really like providing support, or you might dread the idea of having to interact with people. For understanding the technical problems you're solving, support is a great way to do informal research. Recurring issues in support or concepts that users don't get from documentation should inform improvements.

If you're using GitHub, use issue templates. They let you pre-populate the form that users fill out to report a bug: giving their messages more structure makes them more likely to be answerable.

There are some cases where you won't want to open yourself to support requests - if a project is very successful but you don't have time to work on the issue queue, or if it's very technical and there's very little support load. In these cases, you may want to either:

  1. Create a rule specifying that the Github issue tracker is only used for bug reports, feature requests, or other discussion - not support inquiries - and encourage people to use another site for support, like StackOverflow.
  2. Disable the issue tracker entirely and encourage people to communicate by writing code - by submitting PRs. Recently several maintainers have done this, with Ryan Florence writing about it.

Bibliography

Things that I read

Tools you can use to enhance your politeness

Good resources

Books

Screencasts

Building teams

Thanks