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.
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.
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.
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.
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:
Fix typos, broken links, and confusing prose.
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.
Add a license, if the repo does not have one.
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.
Preview of README for Chicago Councilmatic
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?