Holy War or Bikeshedding?

A holy war is a dispute, often but not always over a relatively minor issue, which is not resolvable on the merits of the arguments, but where people feel passionate enough to continue arguing anyway in the hope that their side will prevail. Holy wars are not quite the same as bikeshed paintings. People painting bikesheds are usually quick to jump in with an opinion (because they can), but they won’t necessarily feel strongly about it, and indeed will sometimes express other, incompatible opinions, to show that they understand all sides of the issue. In a holy war, on the other hand, understanding the other sides is a sign of weakness. In a holy war, everyone knows there is One Right Answer; they just don’t agree on what it is.

— Karl Fogel, Producing Open Source Software

The Bikeshed Effect

Although discussion can meander in any topic, the probability of meandering goes up as the technical difficulty of the topic goes down. After all, the greater the technical difficulty, the fewer participants can really follow what’s going on. Those who can are likely to be the most experienced developers, who have already taken part in such discussions thousands of times before, and know what sort of behavior is likely to lead to a consensus everyone can live with.

The principle that the amount of discussion is inversely proportional to the complexity of the topic has been around for a long time, and is known informally as the Bikeshed Effect.

— Karl Fogel, Producing Open Source Software

Compliments Through Criticism

Technical criticism, even when direct and unpadded, is not rude. Indeed, it can be a form of flattery: the critic is saying, by implication, that the target is worth taking seriously, and is worth spending some time on. That is, the more viable it would have been to simply ignore someone’s post, the more of a compliment it becomes to take the time to criticize it (unless the critique descends into an ad hominem attack or some other form of obvious rudeness, of course).

— Karl Fogel, Producing Open Source Software

Feelings Affect Productivity (And Other Things)

It may seem odd to focus as much on the participant’s feelings as on the surface of what they say, but to put it baldly, feelings affect productivity. Feelings are important for other reasons too, but even confining ourselves to purely utilitarian grounds, we may note that unhappy people write worse software, and less of it. Given the restricted nature of most electronic media, though, there will often be no overt clue as to how a person is feeling. You will have to make an educated guess based on a) how most people would feel in that situation, and b) what you know of this particular person from past interactions.

— Karl Fogel, Producing Open Source Software

Orchestrated Agreement Is Often OK

There’s a difference between [all the developers from a single company] actually being decentralized and simply striving to appear that way. Under certain circumstances, having your developers behave in concert can be quite useful, and they should be prepared to coordinate behind the scenes when necessary. For example, when making a proposal, having several people chime in with agreement early on can help it along, by giving the impression of a growing consensus. Others will feel that the proposal has momentum, and that if they were to object, they’d be stopping that momentum. Thus, people will object only if they have a good reason to do so. There’s nothing wrong with orchestrating agreement like this, as long as objections are still taken seriously. The public manifestations of a private agreement are no less sincere for having been coordinated beforehand, and are not harmful as long as they are not used to prejudicially snuff out opposing arguments.

— Karl Fogel, Producing Open Source Software

On The Internet, No-one Need Know You’re Unstructured

Consider this: the only thing anyone knows about you on the Internet comes from what you write, or what others write about you. You may be brilliant, perceptive, and charismatic in person—but if your emails are rambling and unstructured, people will assume that’s the real you. Or perhaps you really are rambling and unstructured in person, but no one need ever know it, if your posts are lucid and informative.

— Karl Fogel, Producing Open Source Software


There does not seem to be much correlation, in either direction, between the ability to write good code and the ability to communicate with one’s fellow human beings. There is some correlation between programming well and describing technical issues well, but describing technical issues is only a tiny part of the communications in a project. Much more important is the ability to empathize with one’s audience, to see one’s own posts and comments as others see them, and to cause others to see their own posts with similar objectivity. Equally important is noticing when a given medium or communications method is no longer working well, perhaps because it doesn’t scale as the number of users increases, and taking the time to do something about it.

— Karl Fogel, Producing Open Source Software

Project Guidelines

At some point, the number of conventions and agreements floating around in your project may become so great that you need to record it somewhere. In order to give such a document legitimacy, make it clear that it is based on mailing list discussions and on agreements already in effect. As you compose it, refer to the relevant threads in the mailing list archives, and whenever there’s a point you’re not sure about, ask again. The document should not contain any surprises: it is not the source of the agreements, it is merely a description of them. Of course, if it is successful, people will start citing it as a source of authority in itself, but that just means it reflects the overall will of the group accurately.

Don’t try to be comprehensive. No document can capture everything people need to know about participating in a project. Many of the conventions a project evolves remain forever unspoken, never mentioned explicitly, yet adhered to by all. Other things are simply too obvious to be mentioned, and would only distract from important but non-obvious material. For example, there’s no point writing guidelines like “Be polite and respectful to others on the mailing lists, and don’t start flame wars,” or “Write clean, readable bug-free code.” Of course these things are desirable, but since there’s no conceivable universe in which they might not be desirable, they are not worth mentioning. If people are being rude on the mailing list, or writing buggy code, they’re not going to stop just because the project guidelines said to. Such situations need to be dealt with as they arise, not by blanket admonitions to be good.

— Karl Fogel, Producing Open Source Software

Your Most Important Skill

The ability to write clearly is perhaps the most important skill one can have in an open source environment. In the long run it matters more than programming talent. A great programmer with lousy communications skills can get only one thing done at a time, and even then may have trouble convincing others to pay attention. But a lousy programmer with good communications skills can coordinate and persuade many people to do many different things, and thereby have a significant effect on a project’s direction and momentum.

— Karl Fogel, Producing Open Source Software

Believing Your Own Hype

Bashing competing closed-source products seems to be more widely accepted in the open source world, especially when those products are made by Microsoft. Personally, I deplore this tendency (though again, there’s nothing wrong with straightforward factual comparisons), not merely because it’s rude, but also because it’s dangerous for a project to start believing its own hype and thereby ignore the ways in which the competition may actually be superior.

— Karl Fogel, Producing Open Source Software

The Potential Effects Of Money

If not handled carefully, money can divide a project into in-group and out-group developers. If the unpaid volunteers get the feeling that design decisions or feature additions are simply available to the highest bidder, they’ll head off to a project that seems more like a meritocracy and less like unpaid labor for someone else’s benefit. They may never complain overtly on the mailing lists. Instead, there will simply be less and less noise from external sources, as the volunteers gradually stop trying to be taken seriously. The buzz of small-scale activity will continue, in the form of bug reports and occasional small fixes. But there won’t be any large code contributions or outside participation in design discussions. People sense what’s expected of them, and live up (or down) to those expectations.

— Karl Fogel, Producing Open Source Software

No Discussions In The Bug Tracker

Make sure the bug tracker doesn’t turn into a discussion forum. Although it is important to maintain a human presence in the bug tracker, it is not fundamentally suited to real-time discussion. Think of it rather as an archiver, a way to organize facts and references to other discussions, primarily those that take place on mailing lists.

There are two reasons to make this distinction. First, the bug tracker is more cumbersome to use than the mailing lists (or than real-time chat forums, for that matter). This is not because bug trackers have bad user interface design, it’s just that their interfaces were designed for capturing and presenting discrete states, not free-flowing discussions. Second, not everyone who should be involved in discussing a given issue is necessarily watching the bug tracker. Part of good issue management is to make sure each issue is brought to the right peoples’ attention, rather than requiring every developer to monitor all issues.

— Karl Fogel, Producing Open Source Software

Zero Tolerance On Rudeness

From the very start of your project’s public existence, you should maintain a zero-tolerance policy toward rude or insulting behavior in its forums. Zero-tolerance does not mean technical enforcement per se. You don’t have to remove people from the mailing list when they flame another subscriber, or take away their commit access because they made derogatory comments. (In theory, you might eventually have to resort to such actions, but only after all other avenues have failed—which, by definition, isn’t the case at the start of the project.) Zero-tolerance simply means never letting bad behavior slide by unnoticed. For example, when someone posts a technical comment mixed together with an ad hominem attack on some other developer in the project, it is imperative that your response address the ad hominem attack first, as a separate issue unto itself, and only afterward move on to the technical content.

If you consistently call out bad behavior, but don’t demand an apology or acknowledgment from the offending party, then you leave people free to cool down and show their better side by behaving more decorously next time—and they will. One of the secrets of doing this successfully is to never make the meta-discussion the main topic. It should always be an aside, a brief preface to the main portion of your response. Point out in passing that “we don’t do things that way around here,” but then move on to the real content, so that you’re giving people something on-topic to respond to. If someone protests that they didn’t deserve your rebuke, simply refuse to be drawn into an argument about it. Either don’t respond (if you think they’re just letting off steam and don’t require a response), or say you’re sorry if you overreacted and that it’s hard to detect nuance in email, then get back to the main topic. Never, ever insist on an acknowledgment, whether public or private, from someone that they behaved inappropriately. If they choose of their own volition to post an apology, that’s great, but demanding that they do so will only cause resentment.

The overall goal is to make good etiquette be seen as one of the “in-group” behaviors.

— Karl Fogel, Producing Open Source Software

Spraying Contributor Repellent

Today’s quote is long but important (bold emphasis mine):

[You] will often find yourselves wanting to settle difficult questions by private communications among an inner circle. This is especially true in the early days of the project, when there are so many important decisions to make, and, usually, few volunteers qualified to make them. All the obvious disadvantages of public list discussions will loom palpably in front of you: the delay inherent in email conversations, the need to leave sufficient time for consensus to form, the hassle of dealing with naive volunteers who think they understand all the issues but actually don’t (every project has these; sometimes they’re next year’s star contributors, sometimes they stay naive forever), the person who can’t understand why you only want to solve problem X when it’s obviously a subset of larger problem Y, and so on. The temptation to make decisions behind closed doors and present them as faits accomplis, or at least as the firm recommendations of a united and influential voting block, will be great indeed.

Don’t do it.

As slow and cumbersome as public discussions can be, they’re almost always preferable in the long run. Making important decisions in private is like spraying contributor repellant on your project. No serious volunteer would stick around for long in an environment where a secret council makes all the big decisions.

Naturally, there are some discussions that must be had privately; throughout this book we’ll see examples of those. But the guiding principle should always be: If there’s no reason for it to be private, it should be public.

Making this happen requires action. It’s not enough merely to ensure that all your own posts go to the public list. You also have to nudge other people’s unnecessarily private conversations to the list too. If someone tries to start a private discussion, and there’s no reason for it to be private, then it is incumbent on you to open the appropriate meta-discussion immediately. Don’t even comment on the original topic until you’ve either successfully steered the conversation to a public place, or ascertained that privacy really was needed. If you do this consistently, people will catch on pretty quickly and start to use the public forums by default.

— Karl Fogel, Producing Open Source Software