Since I released my first open source project in October, I did various iterations at improving the README of my project, but I'm not really satisfied just yet.

I have found surprisingly hard to put myself, who maintains the project and knows every detail of it, in the shoes of the casual developer who would stumble upon my project without any context and not an infinite amount of attention.

Ideally, I would like him after a short read to think either

  1. that's not for me but I know why
  2. that's something for me and I will give it a try.

Do you have any recommendations on how to write a better README?

That could be examples of things to avoid, or examples of projects that do it right.

This post is also available on DEV.