It’s no secret that one of the biggest “bugs” in software engineering, particularly open source software, is documentation. Or, rather, the lack of good documentation. Talking to the founders of the fio and Datasette open source projects, some clues emerge as to how to quash that bug.

Open source “forces me to write really good documentation”

For Simon Willison, who founded Datasette in 2017, needed a better way to query and publish data than Google Sheets. So he built Datasette to make it easy to “take data of any shape or size and publish that as an interactive, explorable website and accompanying API.” One of the reasons he made it open source, he said in an interview, was to avoid a key problem of closed-source code: “You don’t really build it with a mind to having other people use it, which means it can probably go stale.” By contrast, he went on, open source “forces me to write good code. It forces me to write really good documentation.” 

The reasons for good code have been rehearsed before: Developers tend to take more care of their code when others will be able to see it. Fewer shortcuts, better practices. 

But documentation? Willison needs to back that claim up.

SEE: How to build a successful developer career (free PDF) (TechRepublic)

To be fair, Willison may not have always been as focused on documentation. But when his company, Lanyrd, was acquired by Eventbrite, he said it made him rethink his code. In his six years at Eventbrite, the company’s engineering team grew from 100 to 600, spread across three continents. “We had to learn from the open source community. How do you maintain all of this different software with engineers in different places? And the answer was unit tests, documentation, being really disciplined, and code reviews.” 

Today Willison maintains 73 open source projects, many of them mostly alone. Yet he still focuses on the same developer hygiene learned at Eventbrite: “I’m taking the lessons I learned from a 600-engineer organization and applying them to a one-engineer organization.” The result? “My productivity has gone through the roof.” Things that seem like they’d slow him down (like writing good documentation) actually speed up development: “When I come back to the project in two months, everything works, and I know where everything is.” 

But what if you’re not a developer who wants to slow down to write the docs? Or, perhaps even more tellingly, what if you’re a developer who isn’t capable of writing great docs?

“My documentation isn’t great”

This is where Jens Axboe proves persuasive. Axboe created the flexible IO tester (fio) “to save [him] the hassle of writing special test case programs when [he] wanted to test a specific workload, either for performance reasons or to find/reproduce a bug,” as he said in an interview. Fio has since become the industry standard for modeling storage workloads.

What it isn’t the standard for, however, is great documentation, according to Axboe: 

In my opinion, the biggest hole fio has (and probably a lot of other open source projects) is someone writing quality documentation. My documentation isn’t great, and lots of patches for documentation may help make it a bit better, but it’ll never be truly awesome. Not a lot of tech writers seem to be attracted to open source projects, I wish that wasn’t the case.

The lack of great documentation isn’t a surprise, but his idea for where it would come from just might be. I’d always imagined that those writing the code were in the best position to document it. That might work for some developers (like Willison), but others could use help. There are, of course, great technical writers scattered throughout the industry. 

How do we, following Axboe’s reasoning, encourage them to contribute their talents to open source? 

Disclosure: I work for AWS but nothing herein relates to my work there.

Open Source Weekly Newsletter

You don’t want to miss our tips, tutorials, and commentary on the Linux OS and open source applications. Delivered Tuesdays

Sign up today

Also see