Chapter 6. Communications

Table of Contents

Written Culture
You Are What You Write
Structure and Formatting
Recognizing Rudeness
Avoiding Common Pitfalls
Don't Post Without a Purpose
Productive vs Unproductive Threads
The Smaller the Topic, the Longer the Debate
Avoid Holy Wars
The "Noisy Minority" Effect
Don't Bash Competing Open Source Products
Difficult People
Handling Difficult People
Case study
Handling Growth
Conspicuous Use of Archives
Treat All Resources Like Archives
Codifying Tradition
Choose the Right Forum
Cross-Link Between Forums
Announcing Releases and Other Major Events
Announcing Security Vulnerabilities
Receive the Report
Develop the Fix Quietly
CVE Numbers
Common Vulnerability Scoring System (CVSS) Scores
Distribute the Fix Publicly
Further Reading on Handling Security Vulnerabilities

An open source project must do many things: recruit users and developers, encourage new contributors to become more deeply involved, allow free-flowing discussion while still reaching necessary decisions, maintain a body of knowledge and convention that guides newcomers and experts alike, and, of course, produce working software.

Coordinating people to accomplish all this together requires many techniques, and because open source collaboration is ultimately based on software code, most of those techniques revolve around the written word. We'll start there.

Written Culture

The ability to write clearly is one of the most important skills one can have in an open source environment. In the long run it may matter 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 mediocre 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.

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 one 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 or diversity of users increases, and taking the time to do something about it.

All of this is obvious in theory. What makes it hard in practice is that free software development environments are bewilderingly diverse both in audiences and in communications mechanisms. Should a given thought be expressed in a post to the mailing list, as an annotation in the bug tracker, or as a comment in the code? When answering a question in a public forum, how much knowledge can you assume on the part of the reader, given that "the reader" is not only the person who asked the question in the first place, but all those who might see your response? How can the developers stay in constructive contact with the users, without getting swamped by feature requests, spurious bug reports, and general chatter? How do you tell when a communications medium has reached the limits of its capacity, and what do you do about it?

Solutions to these problems are usually partial, because any particular solution is eventually made obsolete by project growth or by changes in project structure. They are also often ad hoc, because they're improvised responses to dynamic situations. All participants need to be aware of when and how communications can become bogged down, and be involved in solutions. Helping people do this is a big part of managing an open source project.

The sections that follow discuss both how to conduct your own communications, and how to make maintenance of communications mechanisms a priority for everyone in the project.[87]

[87] There has been some interesting academic research on this topic; for example, see Group Awareness in Distributed Software Development by Gutwin, Penner, and Schneider. This paper was online for a while, then unavailable, then online again at So try there first, but be prepared to use a search engine if it moves again.