Vermeer, Lady Writing a Letter with her Maid

I want you to write. Not just code. Also words.

If you're a member of the open source community, you can help us by writing about programming, just as much as by actually programming. And writing helps you, too: you can become better known and promote your ideas.

Even more importantly, writing is thinking. There is no more thorough way to understand than to explain in writing.


It doesn't matter how narrow your expertise is. If you know better than anyone how to parse New York City subway schedules, I want you to write about it. If you've taught your cat to care for a Tamagotchi, I definitely want you to write about it. Whatever your expertise is, show me what you know. Then when I have a question about your specialty, I'll know to come to you for help.

For example, the author of HappyBase, a Python driver for HBase, emailed me for advice when he began his project. He knew from my blog that I work on a couple MongoDB drivers, and he had very sophisticated questions for me about connection pooling. Working with him was stimulating, and it was a very efficient way for me to contribute to a popular project.

Being known in your community as an expert or as a cogent explainer helps you. You're more likely to get patches accepted by projects, get talks accepted by conferences, get users, get a job.

Writing an explanation of a bug requires you to think it through, better than any other technique. My faith in writing-as-thinking is so fervent that when I see a tricky bug my first step is to start an article. That is what I did when I hit a bug in PyMongo's connection pool last year. It turns out that in Python 2.6, assigning to a threadlocal is not thread-safe. I am not nearly smart enough, dear reader, to discover such an intricate race condition unless I consolidate each step of the discovery by explaining it in writing.


I notice roughly five formats among the best articles by programmers: stories, opinions, how-tos, how things work, and reviews. If you want to write but you haven't chosen a topic, or don't know how to approach it, this will get you started.


"I'm going to tell you a story about Foo, how it taught me Bar, and led to Baz. First this happened, then that happened. And that's the story of Foo."


We are innately interested in stories about people. You need not be confessional or icky. If I get to know you a little through your blog, your technical articles feel warmer, and I remember who you are.


"Thesis. Points of evidence. Response to likely objections. Restatement of thesis." Just like we learned in high school. The most important thing is that you don't simply have an opinion, but you have a compelling and interesting argument to support it.

Avoid useless controversy like "product Foo is bad" or "Bar is better than Foo." You have nothing to gain by attacking others. Mr. Miyagi says: Karate for defense only.



"Doing Foo is important under the given conditions. I'm going to show you how to Foo. Do this, then do that. There, now I've shown you how to Foo. You should go out and do Foo."

A how-to must be motivated: you must begin by telling your reader when and why it is important to know.


How Something Works

"Do you wonder how Foo works? I'm going to show you how Foo is implemented. It does this and that. Now I've shown you how it works."

Almost every technology I hold in awe has been easier to understand, when I read its source code, than I feared it would be. Writing an explanation of it is a good excuse to dive in and find out.

A "how something works" article need not be motivated. Sure, some readers might want to know how something works in order to use it better. But there are people like me who want to know how almost everything works, and we are your audience for this article. People who don't want to know can move along.



"I read, saw, played, or used something. This is what it is. This is what my experience was like. The thing has these strengths and weaknesses. In conclusion, it's best when evaluated by certain criteria."

It's tempting to evaluate a book, movie, game, or project on a good–bad axis, but this isn't very useful. Mostly describe and analyze instead of evaluating. Tell me what the thing is good for.


  • Technical books! They need not be recent, though staying abreast of publications in your area is good. Reading a book with the intent to review it makes you read more closely, and teaches you about good technical writing too. Here's my review of O'Reilly's "Building Node Applications with MongoDB and Backbone".
  • Others' software projects. But be gentle.
  • Games, movies, music, books that are not about programming: Writing reviews is excellent practice, and warms your blog.

How do you find an audience?

Please don't care about reach. Reach is not the aim of writing about programming. Seth Godin: "Most of the time, you'll aim to delight the masses and you'll fail. So much easier to aim for the smallest possible audience, not the largest, to build long-term value among a trusted, delighted tribe, to create work that matters and stands the test of time."

Since you don't care about reach, don't waste time on SEO. Your goal is not to get lots of hits. You aren't BuzzFeed. Random visitors aren't valuable to you, because you don't show ads. Instead, your goal is to attract specialists in your field so you can share ideas with them. Luckily, you can reach these specialists without much effort.

First, find the aggregator your community reads. I write a lot about Python, and the Planet Python aggregator is by far my best channel for distributing articles. Any article I put in the "Python" category is included in its feed, and that guarantees a few hundred visits. Send a pull request to have your feed included in Planet Python. (And be patient, it's run by volunteers with busy lives.) If you write about another language or technology with a large community, find its aggregators and request to be included in them.

Tweeting your articles has some value. More valuable is posting your article on a relevant subreddit. And use your own home page to send visitors to your best articles, don't just display the most recent ones there.

You can try your luck on Hacker News, but I have concluded that no one serious goes there, so I do not either.

How do you improve?

Write. Emulate the best bloggers and the best articles.

Don't emulate Daring Fireball, GigaOM, or TechCrunch. These are industry news sites, ultimately devoted to one question: which companies' stocks will go up, and which will go down? This is not your expertise. Besides, it's boring. Emulate writers like these instead:

Glyph Lefkowitz. In "Unyielding", he argues that async's greatest strength is not that it is efficient, but that it makes race conditions easier to avoid.

Kristina Chodorow. "Stock Option Basics" tells a personal story about quitting a startup, and describes better than most writers how stock options work. In "Why Command Helpers Suck" she publicly and convincingly criticizes some MongoDB design decisions because they discourage users from advancing their understanding. Her article on MongoDB unittesting is very specialized, but I've referred to it many times since it fills a woeful gap in the MongoDB developer docs. Kristina's funny and amiable voice works well on her blog and in O'Reilly's "MongoDB: The Definitive Guide".

Armin Ronacher. His "Exec in Python" article is long, incredibly thorough, and timeless. It takes an hour or more to read. It took him days to write, I'm sure, and he continued correcting it after publication. It brings insights into the Python 2 and 3 runtimes, how web2py works, and builds an argument for how it should work instead.

Julia Evans is loose and exuberant in her blog, the same as when she speaks. But don't be fooled, her argument for anonymizing conference proposals is meticulous. So is her guide to applying machine learning to business problems.

Graham Dumpleton's magisterial series on Python decorators obsoletes all other writing on that topic.

At Open Source Bridge a group of writers made a list of additional writers to emulate, and tips for improving our writing about programming.

How do you make the time?

Writing doesn't have to be a regular time-suck, because there is no need to publish regularly or often. Most of your value is in infrequent, deep articles. Furthermore, there's no rush to write an article now, because the best subjects are evergreen. Patrick McKenzie: "You can, and should, make the strategic decision that you'll primarily write things which retain their value. It takes approximately the same amount of work to create great writing which lasts versus creating great writing which ages quickly."

(That's my second link to the same essay, it's that good.)

So take your time. When you have a good idea or an unusual experience, you'll be moved to write.


You know something very specific about programming that's worth explaining. Or you have a new way to explain a common topic. Either way, I want you to share your knowledge in writing. Explaining will deepen your understanding as nothing else can. If you don't know what to write about, riff off the ideas I suggested, or get inspired by great blogs. Craft articles of lasting value.