On Mastodon, Matthias Ott asked, What information do you include in the README of a web project? Any great examples you can think of? Do you use a template? Or do you write them from scratch every single time? I started drafting a reply, which broke Mastodon's character limit. So, now it's a blog post.

Anyhow, the structure of a readme often depends on the project, but there are some common points.

  1. At the top of the readme, describe the purpose of the project. Be stupidly simple. State the obvious.

  2. If the readme is for a website, link to the live website. It's surprising how often people miss this part.

  3. If the readme is for a library, document the API. Nothing complicated, just a bullet-list with some code examples. Typescript definitions (typedefs) don't count. And while code should be self-documenting, it doesn't need to be the only form of documentation.

  4. It's often helpful to link to related projects. You give those projects the boost they need, and your users can make an informed decision about your project.

  5. Maintenance info: Is this just a personal project, or are you looking for actively looking for pull requests? Can people expect a quick response to their issues, comments, and pull requests? We're all busy, so there's no judgement here.

  6. For legal reasons, I always include a short note mentioning the license.

That's my two cents. I also wrote another shorter note about this topic. So that's like, 3 cents. Which is very cheap, in case you wanted to buy me a coffee.