« back to blog

Regina Compton

Regina Compton

Ain’t No Party Like a README Party

Because a README Party makes your software more accessible to users

Published on Jan 02, 2017

Every winter, offices around the world celebrate the holiday season with joyous parties, canned food drives, or simple gift exchanges. Co-workers unwind; old friends reunite; teams grow stronger.

At DataMade, this spirit of goodwill and giving extends to our open-source repositories. And so, we welcomed the holidays with a README party! We read and revised several of our most popular README files – making the open-source world a happier, more festive place to be.

Want to party like DataMade? Read on.

Setup

Buy snacks. Sugary, salty, or something in between.

Gather your friends. README parties are not a rubber stamp on your own handiwork! Be sure to invite people with fresh eyes, and divide the workload among different authors and editors.

Gingerbread
Gingerbread cookies by Deborah Lee Soltesz, published under the Creative Commons license.

Get organized. Do not revise a single line of documentation, until you know what work lies ahead. With almost 200 public repos, we had to set limitations: partying too hard can have dire effects. We chose an end time (lunch!), and each party attendee worked through six or seven repos – a number that varied, according to the demands of the code source and the need for documentation.

To jumpstart all this, we wrote “repo-roundup,” a script to help you get organized. It scrapes the GitHub API and returns a CSV file with a list of all repos that belong to your organization.

Repo roundup snippet
Example snippet from DataMade’s "repo-roundup" Google spreadsheet.

You can use the CSV file in whatever way makes sense to you. We imported the CSV into a Google spreadsheet, ordered it by number of stars, added a few organizational fields (such as “checked_by” and “license?”), and started at the top.

Getting started

Talk through a README with your team, and get a feel for the editorial process. What matters most in your documentation? What do you want to standardize in every README? What common errors do you anticipate?

Then, create a list of things to look for in a README. We had a four-step process:

  1. Fix typos, broken links, and confusing prose.

  2. Look for these sections (where appropriate): Description, Setup, Dependencies, installation, Getting Started, Usage, Demo, Team, Errors and Bugs, Patches and Pull Requests, and Copyright and Attribution.

  3. Add a license, if the repo does not have one.

  4. Try to use the code. Do the instructions make sense? If not, make revisions or open an issue with suggestions.

If you need inspiration, then feel free to browse or borrow from the DataMade README template, which provides a basic framework for constructing readable, usable documentation.

Chicago Councilmatic Demo
Preview of README for Chicago Councilmatic

DataMade has several notable repositories, which we think deserve a little celebration. Check out our documentation for usaddress, the Fusion Table Map template, and Chicago Councilmatic.

Suggestions? We accept pull requests!

We sought insight from various sources. Matias Singers put together a list of exemplary READMEs. noffle wrote about the history and reasoning behind the README. And DataMade’s own Cathy Deng wrote a blog post about best practices for documentation.

Have more ideas? Did you recently throw a README party? Are you a fanatic about good documentation?

We welcome your thoughts. Send us an email, open an issue on Github, or Tweet to DataMade!