Lars Wirzenius → I'd like to review your README

I'm afraid I'm not accepting new requests for review. I have reviewed all the ones I've received before 2022-03-24.

I'd like to help others make better free and open source software so I'm making this standing offer: I'll review your README for free.

You have a free and open source project, and would like its README to be good. It might be your first project, or you might otherwise want an outsider's feedback. I'm an outsider. I've worked on free and open source software for decades, as a hobby and as a profession, so I have some experience with reading and writing README files. (I admit my own aren't always excellent examples: it's hard to review your own stuff.)

Here's the process:

  • You email me at liw@liw.fi a link to the README source and ask me to review it.

  • I send you my feedback by responding to your email. If I don't have time, I'll respond by saying that. Check the top of this page for queue status.

  • You can take my feedback or leave it. You're not obliged to do anything just because a random stranger on the Internet has an opinion.

  • If you do make changes, I can look at those too, if you want me to.

  • You can thank me in public, or not, as you wish. I'm not doing this for fame.

Don't tell me anything else about your project. Part of the review process is seeing if the README stands on its own.

I have some conditions:

  • I'm willing to spend a short while per project, not too long. I choose which projects to work on and how many projects. It's my free time, I get to decide.

  • I'm only reviewing the README, not websites and other documentation, nor code.

  • I'm not a proof-reader. You can use spell checker software for that. At best, I'm offering a form of copy-editing.

  • The README must be written in a language I understand. Currently that's English, Finnish, or Swedish.

  • Your project must be in a public version control repository. I don't care where: GitHub, GitLab, something you run yourself, whatever. I don't care what version control system it is. I'll read via a web link to the source of the README.

  • Your project must be covered by a license that is listed as an open source one by the Open Source Initiative: https://opensource.org/licenses.

I do have strong opinions on what a README should be like. I expect the following checklist to evolve over time:

  • A README is meant for someone who is first encountering the project to be able to quickly decide if they want to learn more about it.

  • A README should have a "blurb": a very short, dense summary of the project aimed at someone who doesn't know anything about it yet and may not know the topic area.

  • A README is not the manual, but it may have an example of how to typically use the software, especially if that helps the reader understand the software better.

  • A README should say how the copyright and other legal aspects affect the project. It should say what copyright licenses the project uses.

  • A README can also contain instructions for installing the software, or how to run its test suite, and other practical aspects, but those can go into other documentation as well. Referring to them is good, as is linking to more information about the project, and who works on the software.

I'm not publishing the reviews I make, or the links to READMEs I have looked at or that are in my queue. If I were a fresh open source developer, I wouldn't want some random stranger publishing reviews or my own stuff. I'd be too scared of a bad review to ask for a review.