See a typo? Have a suggestion? Edit this page on Github
This blog post was previously titled "Manipulating Maintainers," but has been retitled to more accurately reflect what it's about (with a less cheeky tone). It's about how to most effectively interact with and request assistance from maintainers of open source projects, and open source community members in general.
There's an old "ha ha, only serious" joke. If you go to a Linux forum and ask for help fixing your WiFi driver, everyone will ignore you. If, instead, you say "Linux sucks, you can't even get a f*&$ing WiFi driver working!" thousands of people will solve the problem for you.
This story is a great example of manipulating people, but it's obviously a negative take on it. I'd like to share some thoughts on this from a much more positive standpoint, which will help you get people to pay more attention, be more helpful, and—perhaps most importantly—create a healthier open source community over all.
These items will appear in no particular order, and will almost all fall into either the attractor or obstacle category. An attractor is something you can do to make people want to participate with you. An obstacle is something you should not do, which would prevent people from interacting with you.
And it should go without saying, but I'll say it anyway: this is an opinionated list, written by one guy. I'm including in here things that I personally care about, and things which friends and colleagues have shared with me. No example is specific to any individual, so don't think I'm calling you out: I'm most certainly not. And some people may disagree, or have other items for this list. Sharing such differing thoughts would be very healthy.
Don't waste people's time
This is my biggest one to be honest. Remember that for the most part, people you interact with in open source settings are doing this in their free time. Either because they love a project, they want to help people, they want to change the world, or something else. You're asking for a slice of their lives. Make that slice as small as possible.
The advice is vague, so let me follow up with some concrete examples:
- File a good bug report. If you write an issue that says "my code doesn't compile," and don't include the error message, full code, OS, compiler version, and other such things, people will have to spend time prying it out of you. Be forthcoming with relevant information.
- In slight contradiction to that: be concise. Start off with the most highly pertinent information. Make it clear what you're trying to do. If you have a 400 line error message, perhaps put it in an lpaste or Gist and link to it.
- Provide a minimal repro. "Here's a link to my 1500 SLOC project that doesn't compile, kthxbye" is a bad start. As someone helping you, I'm going to have to strip off the extraneous bits until I'm staring the problem in the face. Why should I spend my time doing that, when you—the person asking for help—could be?
- Make sure to mention any custom configuration. If I spend 5 days trying to fix an issue with your code not linking, and then you say "oh, I've been trying out the prerelease linker, I forgot to mention that, you think that could be the problem?" I'm going to be annoyed. Don't do that. Be forthcoming with all relevant info, and call out in particular custom things on your system.
- Don't fall into the XY problem. And don't get offended if you get accused of hitting the XY problem. Instead of trying to explain what this problem is, I'll just provide a link.
Demonstrate you've tried
You've been staring at your screen for the past 5 days. The code hasn't compiled. You have no idea why. You're pulling out your hair at this point (side note: bald is awesome). You finally, in a fit of desperation, go to Stack Overflow and say:
I'm trying to make an HTTP request in Haskell and can't figure it out. Any advice?
Good luck. Not only is your question vague, but it sounds like you're asking for help on a homework assignment and are too lazy to do any research. Make it clear that you're not just getting someone else to do your work, and are really deserving of assistance.
Below you'll find a snippet of code I've been trying to get working to make an HTTP PUT request and parse the response body as XML in a streaming fashion. As you can see, I'm trying to connect the source body to the
parseXMLfunction fromxml-conduit, but I get the error message below. If anyone could point me in the right direction, I'd appreciate it.
Make sure to include the import statements and language extensions too, so that anyone reading can just copy-paste your example and get the same error message. (I like using reproducible Stack scripts for this.) You may notice an overlap with minimal repro from above: that's intentional.
Help other people
If I see people answering questions on a mailing list or Stack Overflow, I'm appreciative. I consider them a comrade-in-arms. And I consider them assets to the community. They've earned my respect, I'm indebted to them, and I want to entice them to continue. Honestly: all of you helpers are awesome in my book. If one of those people asks a question, I want to help more.
In addition to all of the feelings I mentioned above, there's also a more basic one: if this person is having trouble, it's probably not the most basic, boring question. In reality, the person may be barely a beginner, and may be asking beginner questions. But I know statistically that just having that helpful person's name associated with the question increases the likelihood of it being interesting. In other words: I'm nerd sniped.
This points out something which really applies to all of these sections: people have memories. As soon as you start interacting with the community, you're building a reputation. You can change that reputation over time (for better or worse), but you have to acknowledge that it's there.
Don't be rude
Compare:
Thank you for your great software, I really appreciate the time you've taken to make it. I'd appreciate your help with...
With:
I've been pulling my hair out trying to parse your documentation for the past two days. You think you can help me make sense of it? I'm trying to...
And even further:
Since I'm stuck using your piece of s*&# software with crappy documentation, the least you can do is help me overcome...
If your goal is to get someone to help you, I'd place a large wager that the first approach will attract the most assistance. It doesn't matter if the other two approaches really do capture your current mental state. Are you trying to vent at someone, or get help?
I recently had someone argue a few times that the tone of a question shouldn't matter. (In fact, those interactions were partially what encouraged this blog post.) I argue that that's not only naive, but dangerous:
- We're human beings, and we like being treated nicely. As I mentioned above, open source community members are giving up a portion of their lives to help strangers. You should make that sacrifice feel as rewarding as possible.
- Rude comments like this scare other people away. Encouraging people to continue with them by rewarding them with a helpful answer has the real possibility of scaring away more constructive community members.
- All of life is a series of choices between different things I can be doing. If you make it miserable enough to interact with you, I may very well choose "watch paint dry and see this jerk badmouth my project in public" over "give this guy any more of my time."
- Whether correct or not, being rude is a signal to me of other likely tendencies. I'm likely to guess that someone rude is also selfish, unwilling to minimize time wastage for others, and unlikely to contribute back by helping people. If I have to make a snap judgement on you based on a question and your tone of voice, a rude tone is not going to help you.
I honestly haven't found the best approach to this specific problem. In some cases, a private message saying "your message would be more well received if you modified it" can help. But if I'm honest, by the time I think about writing such a message, I've basically decided that this is a person not worth my time, and trying to encourage him/her to behave better isn't worth it.
The situation is slightly different if someone has been in the community for a while, and suddenly has an outburst of rudeness. I'm not excusing it, but I am saying I'd be more willing to consider that he/she is having a bad day, or that the problem is really bad, instead of "this person is just a jerk." Also, the reverse is true: if you've been rude to someone for the past 10 interactions, it may be very difficult to convince them to help you on the 11th, even if the rudeness disappears. (Overwhelming niceness, however, can help.)
Side note: I implied above that the project documentation sucks. That may be the case. See "offer to help" for advice on pointing that out.
Say thank you
I'll preface this one with a few caveats so I don't get a flurry of guilt-ridden "thank you" notes. Most people don't say thank you in open source. I rarely write a thank you note to a package author. I don't expect it, I've never met anyone who expects it, it is not necessary.
When someone has received assistance on a mailing list, I get happy. When that person responds with a sincere thank you, I get happier. When I'm the person who did the helping, I'm even happier still. It's simple, it's trivial, but it's often missed. Most people are only doing open source work to help others. Gratitude may be their only reward.
Taking it a step farther: there have been a few times over the years where, out of nowhere, I've received a very kind personal email thanking me for work I've done. You can ask my wife and she'll confirm: it's truly touching to receive such messages.
I know I've had views of open source maintainers as being far beyond the lowly likes of me in the past. I don't think it's generally true. Most people are, at the end of the day, just people. And they respond like any other people to kind words.
Though I have a feeling that Linus Torvalds may be a bit confused if you pop him an email saying "love Linux, thanks!"
Admit if you're new
This one works one time per community. If you're new, you don't know what you're doing, and are asking for help, say straight out that you're new. It will get you some sympathy (unless you're lying, then people will hate you). It will get a more softball answer, and likely some guides to places explaining how to interact better. For example: if you come to the Yesod issue tracker and say "I'm new, I'm not sure if this is the best place to ask about installing GHC," you'll likely get pointed to an install page and Stack Overflow for further "please help me" questions.
Offer to help
This may be the first surprising piece of advice. Let's say the docs on my library suck. You could come in and say "help me solve X because your docs suck." And I might answer. Now consider this:
I was having trouble doing X with your library (thank you for it by the way!). I'd be happy to prepare a documentation PR to help other people in my situation, if you'd be able to guide me towards an answer.
Whoa, what is this? Help someone and they'll take away the dreaded documentation writing task from my plate? Awesome, I'll get right on it!
In addition to docs, similar thoughts apply to:
- Offering to write test cases
- Offering to add some missing functionality
- Offering to answer people's questions on other issues/the mailing list/Stack Overflow
The point is: convince the maintainer (or whoever) that giving time to you is an investment.
Give money
This isn't at all a universal one. And to be clear: I'm not asking for it, if I have an envelope with unmarked bills on my doorstep tomorrow, I'll be weirded out.
Some people just need money. They like contributing to open source work, but they have to pay the bills. If they've at all expressed a willingness to accept money for their work (like setting up Flattr or Patreon or whatever is popular these days), considering donating.
Consider how much of their time you're taking. Consider how much of your time they would be saving you. Consider what a typical software developer hourly rate is. And then realize that buying someone a beer, or even a nice dinner, is probably a cheap price to pay for an answer to a question.
And for those who aren't asking for any money, offering to buy the beer/coffee/soda when you meet up at a conference is a nice way to make this one a reality too.