Job No. 1 In Open Source: Making Sure Others Can Understand Your Code


Matt Asay

October 30, 2014

It’s convenient to believe that the only thing that matters in open source development is code. But communicating about that code is just as important, if not more so. 

Small wonder, then, that New Relic’s Andy Lester puts “strong writing ability” at the top of his list of “8 essential traits of a great open source contributor.” It’s not merely a matter of marketing a project to would-be contributor. It’s primarily about getting along and inviting the right kind of contributions. 

Speaking Clearly About Code

While I’ve pointed out the importance of hiring exceptional writers to help craft and articulate meaningful stories about why a product matters, the reality is that strong writing skills matter just as much for developers as for marketers. In part this is a matter of developers doing a better job of marketing their projects to rally contributors, but it’s actually much more fundamental. 

See also: Why Open Source Is Becoming A Big Developer-Recruiting Tool

As Martin Fowler declares, “Any fool can write code that a computer can understand. Good programmers write code that humans can understand.”

But it’s not just the code that needs to be clear. The conversations around the code need to be even clearer, as Lester writes:

Almost everything done in open source is done through the written word. Documentation, bug reports, discussion of implementation—everything is written out and your message must be easily understood. Lots of people can code, not as many of them can clearly communicate what they’ve done. No one contributes only code to a project. Code must be documented, and patches contributed to the project should include a summary description of what’s been done. Without clear explanations of your actions and their intent, the chances of your code being accepted into the project are greatly diminished.

Apache Storm creator Nathan Marz echoes this, stressing the importance of well-written documentation:

[After announcing the project,] I spent the majority of my time writing documentation for Storm. This is the single most important thing I did for the project. I wrote about 12,000 words of carefully thought out documentation—tutorials, references, API docs, and so on. A lot of open source developers don’t realize how crucial docs are: people cannot use your software if they don’t understand it. Writing good documentation is painful and time-consuming, but absolutely essential.

That is an amazing statement. Many developers would think their job was done once they’d written the code. But it’s not. Not even close. The real work begins with documentation and continues with all the chatter on mailing lists and elsewhere that helps elucidate the how and why of an open-source project, something that Facebook’s open source chief James Pearce also calls out.

Speaking Kindly About Code

On the Internet, no one knows if you’re a dog, but everyone knows if you’re a jerk. This is especially true in tight-knit open-source communities, where collaboration is critical. 

See also: Want To Start An Open-Source Project? Here’s How

Of course there are plenty of examples of project leads that flame would-be contributors for half-baked or merely different ideas as to the right approach to an engineering problem. Linus Torvalds, for example, admits to a “metric s—load of [mistakes he’d] like to fix” related to “alienating users or developers” through “strong language” and abusive behavior.

But part of coding well is writing kindly, as Lester goes on to note:

The best contributors understand that the people at the other end of an email thread, or talking in IRC, or discussing a bug in a GitHub issue ticket, are also human beings who may not always have a lot of confidence in their skills and value. Great contributors nurture and bring forth the best work from others by being encouraging and helpful. 

This isn’t about mollycoddling newbies. It’s about nurturing newbies to help them become full-fledged contributors. Flaming someone is never the right response to bad code or even bad behavior.

Not if you want your code to get used, that is. Stack Overflow co-founder Joel Spolsky puts it this way:

The difference between a tolerable programmer and a great programmer is not how many programming languages they know, and it’s not whether they prefer Python or Java. It’s whether they can communicate their ideas. By persuading other people, they get leverage. By writing clear comments and technical specs, they let other programmers understand their code, which means other programmers can use and work with their code instead of rewriting it. Absent this, their code is worthless.

Pretty bold. Also true.

Get Used To Writing

It continues to surprise me how essential good writing is to developers, but also to other professionals. Astrophysicist Kirk Borne, for example, suggests that strong communication is critical to data science. It’s not enough to understand data and talk to machines; at some point you need to interact with humans.

As the world moves online, strong writing ability will become ever more important. So as much as we rightly worry about a decline in science and mathematics skills in education, we should be equally concerned by our ability to communicate about these topics. 

Just as business schools increasingly teach ethics, maybe computer science degrees should be awarded only after wading through a fair amount of Flannery O’Connor, Sylvia Plath and a creative writing class. Or five.

Lead photo of The Bell Jar by kristina

Great ! Thanks for your subscription !

You will soon receive the first Content Loop Newsletter