A year ago I published an offer to review the README of free and open source projects. I didn’t expect much interest, but someone posted the link to Hacker News, and I got enough requests that it was a little overwhelming. I’ve now reviewed 196 READMEs, my queue is empty, and I’m suspending the offer for now, even if it has been fun.

I especially wanted to help people new to FOSS development, and I know that for one’s first project it can be scary to open oneself up for critique. Thus I made it possible to request a review in private, and sent my feedback in private, and I haven’t published the projects I reviewed. However, I feel it might be of interest to read a summary of my experience doing this.

Overall, I was pleasantly surprised at how good the READMEs were. People put in a lot of effort into them. There might be some selection bias here: someone who doesn’t care about making a good README probably won’t ask for a review, either.

It seems to be common now to have a screenshot or an animated GIF of the user interface of software, in addition to a textual description. I find this to be an excellent idea: it gives the reader an immediate look at what the software is like. For code libraries examples of using the library serves the same purpose. A link to a demo is often quite illuminating to the reader.

I find it quite useful for a README to start with an explanation of what the software does, and what one could achieve with it. It seems worth it to me to be explicit and not assume the reader will figure it out themselves.

The READMEs I was asked to review were divided into roughly four categories:

  • A short calling card that just tells you what the aim of the project is.
  • A “getting started using the software” type of document.
  • A more thorough introduction to the project as a project: who works on it, what it’s background is, how to contribute, etc.
  • An in-depth manual.

I tend to prefer the shorter approaches, but it is a matter of taste and goal.

It’s important to consider the audience. For a README, the reader may land on it via a web search, and might not know the topic area of the project. Even so, they might be interested in it, once they do understand. I find it useful for a README to explain things to a random passer-by in a few words, or to link to an explanation elsewhere. As an example, if a README says the project is a library of some kind, it may be useful to say it’s a code library rather than, say, a collection of cultural works. The sooner one makes that clear, the less time others will spend figuring out if the project is what they’re looking for.

I’m suspending my offer to review READMEs for now. I feel this is something that anyone could do: you, too, can do it. Why don’t you? It’s easy, and it turns out people appreciate it.