Person A has a problem, and can’t find a solution in the project documentation. She eventually figures it out for herself, and when Person B comes along with the same problem, confirms that she had the same issue, notes the documentation didn’t solve it, and points to her solution.
Developer A notices. He tells Person A that if she can write her solution up as a FAQ entry, like the examples he shows her, he will see that it’s posted on the FAQ so that everyone can share her solution. She does so, and finds other problems she can fix. They are very small – but Developer A keeps taking the time to assist her. Eventually she starts contributing larger chunks of content. Developer A arranges for her to get commit access and as the years go past she writes tens of thousands of words of documentation and becomes a strong advocate of the project, writing articles that get published all over the web about just how awesomesauce this project is.
More recently, Person A notices someone in another project have a problem she has also had. Their documentation is excellently written, but there are some knowledge gaps and some parts are hard to find, even if you search willingly and carefully. She chimes in with Person B, pointing out she’s had some of the same problems with the documentation. She can’t point to an exact solution as this situation is far more broad, but she points Person B to some documentation she had written of her own that she thought might be of help to him.
Developer A notices. He informs her that she is wrong, and the documentation she is looking for does in fact exist. He links her to this documentation to prove it. She clarifies that whether the documentation existed or not, a genuine search did not find it for her and this perhaps shows there’s a problem of visibility. This being IRC, private messages telling her that she is an idiot and should stop asking to be spoonfed start rolling in. No-one on the internet can resist an opportunity to argue.
Unfortunately, the situation quickly gets out of hand from there. Developer A, joined by Developer B, have a full-blown argument with Person A who is becoming less and less coherent as she tries to explain her position and ignore the private message windows lighting up with insults. Developer A and B are convinced she is insisting that the documentation they showed her does not exist. Person A cannot understand how this can be read from her saying the documentation is hard to find. Developer B seems like he might have actually been a helpful person to her if she had spoken to him first, as he at least is listening to what she has to say rather than rebutting arguments she has not made. Unfortunately it was Developer A who answered first and Developer B has come into the situation assuming that Person A is trying to be difficult, rather than realising Developer A has managed this situation poorly and contributed strongly to the escalation. Person A, also being a nerd on the internet, gets sidetracked into arguing who is right instead of actually arguing her point.
Once she realises that the situation cannot be salvaged, Person A flees vowing not only that she will not contribute to this project, but regretting that she must still use their product. Developer A and B are gleeful, thinking they have proved that this person was not going to do any work for them anyway.
Person A is still the same person, with the same skills and the same willingness to help out with documentation as she loves to write. She knows their product well, and would be very capable of starting to fix the documentation knowledge gap. How did it all go so wrong?
Obviously, Person A is me. I managed to get into such a dreadful argument on a project IRC channel earlier today that I was accused of trolling. The accusers hadn’t been involved from the beginning and had only seen me stubbornly repeating the same rebuttal to someone who was just as stubbornly repeating back the same fallacy they’d attributed as being said by me. From that perspective, I can completely understand where they are coming from – but I also firmly believe that this community created the situation in which someone who usually communicates well and has a proven history of contributing to open source projects and a willingness to help with theirs is turned into an angry and somewhat accidental troll.
In the first scenario, a representative of the project notices my interest in the documentation and encourages me to help out and fix it. He lowers the barrier by showing me exactly how to start. If I write something that is like this specific example here, I can email it to him and he will take care of the rest. These are simple steps a new person can easily follow. In order to continue contributing, I must eventually learn SVN, Docbook, and how to create diffs of XML documents. At every stage, the Developer helps and his work pays off when I become a fully autonomous writing machine, no longer needing his help and able to in turn help others. His initial investment in time however was very slight – a short discussion on IRC, a URL, and an offer to mark up and commit my documentation if I did in fact write anything he could use. No more than five minutes of his time would have been wasted if I had turned out to be trolling and as it turned out his risk was well spent and the gain to the project was measurable.
In the second scenario, the Developers think they are being helpful but they’re starting from a much more argumentative position. Their refusal to accept that there is a problem in the first place that I would be willing to help with wastes everyone’s time. They believe they are playing a trump card by insisting that I go to the wiki and just ‘click edit then!’ but this doesn’t wash – I know that it should be more complicated than that to edit a project’s finalised documentation! – and by the time they suggest this action everyone is angry and unwilling to cooperate. As a last ditch effort I ask for information online on how to contribute documentation – a style guide, a glossary, anything that would lower the barrier – and is told it does not exist. Developer B admits that perhaps this is a gap that should be filled and I could help there – but by now no-one involved in the conversation has any interest in helping anyone.
Many open source projects become their own worst enemies in situations like this. Attracting new contributers is necessary for a project to survive, as long as those contributers are genuine and have skills the project can use. Unfortunately, to someone trying to break into a community it’s not obvious at times where to go or who to talk to. IRC and mailing lists become the first point of contact and those project members who are most aggressive and argumentative are the ones who respond.No matter how knowledgeable these members of the community are, aggression is the antithesis to good communication. Someone being WRONG on the internet turns very quickly into a situation where being right becomes more important than actually trying to understand what this person is saying.
The saddest thing about this whole situation is that so often, the fact that the outsider was driven away is seen as the project members winning the argument. They believe they’ve proven that they are right, and that they’ve succeeded – when really, by any measure of benefit to the project, they’ve quite clearly failed.
I really, really love my android. It’s the last thing I put down before I go to bed at night, and the first thing I pick up again in the morning. Not only do I not miss my iPhone at all, but I find I take my laptop out of my bag less and less, preferring to rely on my phone for most tasks. 
