Fixing Docs One README at a Time

GitHub's recent survey reveals 93% say poor documentation is a problem. Learn how the new project Feedmereadmes can help.

Lauri Apple"Documentation is highly valued, frequently overlooked, and a means for establishing inclusive and accessible communities," the GitHub team notes in their brand-new Open Source Survey. Based on 5,500 responses, the survey reveals that 93% of respondents say "incomplete or outdated documentation is a pervasive problem." However, only "60% of contributors rarely or never contribute to documentation."

These stats won't surprise anyone who has spent more than a few minutes clicking through GitHub repositories. How many times have you clicked on a GitHub repo, skimmed the README, and thought: "Sounds interesting, but what does it actually do?"

If the project's creators were your own colleagues, you were probably able to follow up with them in person or over chat. If the project creators were on the other side of the planet, you probably posted your question as a GitHub issue. But if you were pressed for time, you just as likely moved on to find a different project whose README offered the assurance you needed to solve the technical challenge you faced. Other reasons might have prompted you to move on: the project had no license, no contributing guidelines, or no guarantees that the maintainers would ever respond to your pull request. All of these issues are so simple to fix, and can pay off significantly as your community (or other open organization) works to recruit new participants. And yet working a little Markdown magic somehow becomes an afterthought. Sad!

How many times have you clicked on a GitHub repo, skimmed the README, and thought: "Sounds interesting, but what does it actually do?"

So a few months ago I decided to tackle this problem. I created Feedmereadmes, a help exchange aimed at making the world's READMEs more readable by offering free writing/editing services and project analysis to open source project creators who want README help. It also gives writers and editors who want to get involved in open source—but aren't sure where to start—an opportunity to contribute. In creating the project, I wanted to create a place for developers and writers to mingle, collaborate, and share their knowledge so that we could create READMEs that anyone could generally understand.

We need thee, Feedmereadmes

Feedmereadmes' target audience is broad: the universe of individual project creators and small teams who don't have budget for editorial services. Maintainer.io is a new outfit that offers similar services (plus a whole lot more—check them out) for companies looking to add polish and professionalism to their open source initiatives. One of their founders runs the Awesome README list, a valuable resource for all things README; he kindly added Feedmereadmes to the list not long ago.

Clearly, efforts like Maintainer.io and Feedmereadmes address a longstanding need. Calls for better documentation predate GitHub, and given the high velocity of GitHub's growth (20 million repos and counting) this need has only become more evident.

Back in 2010, GitHub founder Tom Preston-Warner chimed in on the topic with a still-popular, still-prescient post on "README Driven Development," in which he advocated writing your README first. "First. As in, before you write any code or tests or behaviors or stories or ANYTHING," he wrote. "I know, I know, we're programmers, dammit, not tech writers! But that's where you're wrong. Writing a Readme is absolutely essential to writing good software. Until you've written about your software, you have no idea what you'll be coding."

Years later, documentation remains an overlooked part of OSS development for many. The result:

• READMEs that come without basic install/run/config instructions, creating needless friction for potential users and contributors.
• READMEs that don't explain the "Why" and "How" behind the project—why it exists, why it's different from similar projects, how it's used in production by the creators or others, and how it's architected.
• READMEs that are either too short or too cluttered.

In February 2017, while listening to Rich Bowen speak at FOSDEM about documentation foibles and fails, I started thinking about what could reduce the world's collective, doc-generated sadness quotient. Titled "Read The F* Manual? Maybe you need to write a better f* manual," Rich's talk focused on the need for OSS project creators and maintainers to listen to their audiences and welcome newbies. It encouraged the audience "to see entire project communit[ies] as its documentation"—an idea that transcends the "developers don't like to write docs" stereotype (hey, a lot of writers don't like to write either!) and "the code speaks for itself" mythology. "Take a moment to understand why people are asking you 'that stupid question,'" Rich told the FOSDEM crowd. "Often the problem is that your docs are terrible or confusing."

Energized by Rich's talk, I found him afterward in the exhibit hall to thank him for the inspiration. While we were chatting, an idea emerged: offer free writing and editing services to project creators. A short walk and a Belgian waffle later, Feedmereadmes sprang from GitHub's womb, wailing rather baby-like to address its hunger pangs.

How Feedmereadmes works (and for whom)

For project creators, the first step is to link a project's READMEs via the "Issues" feature. They can also tweet their README link to @feedmereadmes and I create an issue for them.

Next, I edit and proofread the README. In the pull request message, I ask maintainers some questions to help them clarify their project purpose. If it's not clear why they made the project, how the project works, and what the project solves (along with some supporting evidence describing how the project solved an actual problem), I include these questions along with some supporting resources for additional context. Mozilla's Open Canvas, 18f's open source guide, and the README and product analysis templates we've created at Zalando are my typical go-to's.

When writers and editors want to get involved, I simply direct them to the Issues tracker and invite them to claim a project to help. The README I created there contains a link to a GitHub tutorial for first-timers. I also include a few words about the rationale behind working for free. As a former journalist, blogger, and copywriter, I'm pretty sensitive to the fact that many companies and entities offer "free exposure" as compensation. For writers struggling to make a living from their craft, "free publicity" won't pay for rent or Indian food. With that in mind, I include this note:

[T]hink carefully about why you want to contribute your writing and editing skills to making the world's READMEs more readable. It might be to increase your knowledge of technology and open source; collaborate with creative people; help a struggling developer improve their project in a way you find simple, but that they might find difficult; or build your portfolio with different job prospects in mind. Maybe you're attracted to FOSS's spirit of free exchange and information sharing. These are just some of the reasons why many of us all over the world spend our nights and weekends at our computers, doing work for no monetary compensation.

I also add a bit of advice that has helped me achieve greater fulfillment in work: "Go where it's warm." In other words, help people who appreciate you and make you feel like you belong. If project creators are taking advantage of you or making you feel uncomfortable, find another project. Seek collaborators who make you feel respected, appreciated, and "one of them." Don't settle for less.

Since the project started in February (it's now June), I've added another target audience: product managers and specialists who want to contribute to open source. This idea, like the project itself, came about serendipitously: through an informal conversation with a talented colleague and product specialist looking for an entry point into GitHub. We haven't identified an opportunity for him to start contributing yet, but the business insights he brings to the project could really help our audience elevate their work.

Feedmereadmes (seriously, I mean it)

Unfortunately, Feedmereadme's audience remains pretty small at the moment. One reason might be that projects needing better documentation might be less likely to proactively reach out for support, or even go looking for it. With this in mind, I've recently begun reaching out to projects offering to help. While some project creators don't respond, most are happy to receive another contributor willing to invest time into their work.

As for the projects that have requested README help, probably the biggest lesson I can pass on is this: Make an "EZPass" option for documentation-related contributions. You can do this by allowing contributors to fork and fix your READMEs. Imagine being a really sharp but novice technical writer who comes to your project, full of enthusiasm to edit all of your uncapitalized sentences and misspelled words, but sees a list of requirements to install packages and comply with rules meant to circumvent authoritarian and chatty bots. That person is likely to move on; you've just overwhelmed them.

Taking a more README-driven development approach would also help project creators stay on top of documentation creation, and likely enhance overall project accessibility. The code doesn't always speak for itself. It often doesn't even speak to those of us who wrote it, after some time passes and we've forgotten what exactly we were thinking in that moment of inspiration. As my colleague Bill de hÓra says, "documentation is a high-leverage activity that keeps you focused on outcomes and what you want to achieve. Far from being overhead, documentation pays off by giving your users and colleagues the context to understand what the project does and why."

Even if you don't agree with my colleague Bill or Tom Preston-Warner, you can still make sure your README is user-friendly to the extent that you want to work on them. I advise defining the "user" broadly to include your colleagues, your language community, your manager, your idols, journalists, fellow FOSS addicts who are in a hurry, and your parents. (You want your parents to be proud of you, right? Help them along by making it possible for them to understand what you're doing. Tell a story others can comprehend.)

Conclusion

While "improving my docs" may still seem like the "giving up smoking" or "taking a run every day" of open source development, we project creators (93%!) know we need to do it. And yet many of us don't make it a priority. Hey, that's fine, millions of GitHub contributors—when you're ready, we'll be here.