The Awesome Power of Well-Documented Code

· 4 min read
The Awesome Power of Well-Documented Code
Photo by Markus Spiske / Unsplash

Okay nerds, this one’s for you.

Back when I was researching my book Coders, I talked to a lot of folks who ran very successful open-source projects.

“What”, I asked them all, “made your project take off?” Why did yours gain legs, when so many others — including quite good projects — languished, and never attracted much interest?

Most of them all said something that warmed my little programmer-and-liberal-arts-nerd soul:

“We had really good documentation.”

“Documentation” — for those who aren’t already hipdeep in the swamps of software development — means what it sounds like. It’s when the coders sit down to write careful instructions on how, precisely, someone else can use their open-source code. Often they’re writing these instructions for other coders. For example, a few months ago I tried using the Kaboom javascript software that helps you write little video games, so I used their documentation and tutorials.

Documentation is all about being an excellent writer. Specifically, it requires us to do something quite challenging: To imagine ourselves in the shoes of someone who’s never used our code … so we can carefully guide them through. We have to develop a strong theory of mind for the newbie. We have to dispense with as much jargon as possible, and intuit the things about our code that might seem awkward or baffling at first.

Many software developers are terrible at this. To be fair, most everyone is bad at it; hell, I know full-time journalists who fail at this task all the time.

The writing of documentation is, in other words, a liberal art.

And if you’re good at it? Holy crap, it can really make your open-source project explode in popularity.

I first got a sense of this talking to Mark Otto, who in 2011 along with Jacob Thornton created “Bootstrap”, a little bundle of code that helps you quickly design and style a web site.

Bootstrap began life when Otto was working at Twitter, and wanted to help developers inside Twitter make their tools be more user-friendly and attractive. So he put together the Bootstrap code; drop it into your HTML, and you suddenly could make lovely grid layouts. Crucially, he wrote up clear and engaging documentation, including examples of how to use it.

Then Otto decided to show it off at an internal Twitter week-long hackathon. At the beginning of the hackathon, he showed the Bootstrap code — and his documentation — to the 75 teams of Twitter developers, and encouraged them to use it. He also told them to reach out if they had any questions about Bootstrap, or how to use it: “Put me to work if you need me,” as he recalled saying, when I interviewed him.

Over the week, it didn’t seem like many folks were picking up on Bootstrap, though. Out of 75 teams, only two asked him questions. Still, Otto regarded those two questions as real validation: “I was like, oh awesome, incredible success, this is huge.

In reality, Bootstrap had gone utterly viral at the hackathon. When the 75 teams showed off their code, fully half of them had used Bootstrap.

But: Why hadn’t they reached out to him?

Because they didn’t need to. His documentation was top-notch. It spoke for itself. It was clear, precise, captured all the confusing things that might trip up newbies, and included lots of examples of how to use the code.

Over the next few years, Bootstrap exploded in popularity. When I was writing about it in the mid-2010s, it had been Github’s most-popular repository of code for a few years. Today, it’s still the fourth-most-starred library.

If you want to know why Bootstrap took off? Well, it’s obviously because it solved a problem for tons of coders. It was elegantly made.

But that wasn’t enough for success. There are tons of software projects that check those boxes, and they languish in anonymity.

What set Bootstrap apart was its first-rate documentation. When Thornton and Otto released Bootstrap to the world in 2011, they set up clear, sparkling docs that walked people through tons of live examples of how the code worked. As Otto told me …

We told you how to do those things, and then we gave you a live rendered version of it — with the code right below it. And no one was really doing that, at that point! It seems kind of trivial now to do that today. But no one had just really easy docs, with live examples that I could just copy and paste and just run with it.

I still encounter this over and over again. I’ve recently been researching the growth of Rust, for a big piece on its history for MIT Tech Review. (It’ll be out in the spring issue, woo!) Now Rust, like Bootstrap, has inspired a massive amount of devotion; for six years running, it has topped the Stack Overflow “most loved” category in their annual survey of languages.

And one thing that I’d long heard about Rust? It had wonderfully written documentation. Rust is a bit complex to learn; it requires coders from languages like Python or JavaScript to think much more about memory than they’re accustomed to. But the many folks who’d been honing Rust’s docs — including major contributions from Steve Klabnik and Carol Nichols — had written truly crisp documents. I once spent a weekend tinkering with Rust, a total stumbling-around newbie, but I never once felt lost.

One of the key things about amazing documentation is it helps the newcomer from getting blocked, and drifting away. If you’ve truly specced out what a newbie needs to know, then they’ll be able to keep chugging along more often. They’ll less often get stuck asking for advice in a forum that never comes. (Most of alll, they won’t need to pester you, the overworked open-source developer.) They won’t bounce off your project, deciding, eh, this is too hard to figure out.

So, the lesson is: If you have some open-source code you want to share with the world? If it’s useful code, great! If it’s elegant, even better!

But if you want it to take off, write fantastic documentation.