[avgcorrection]

> https://github.com/appsmithorg/appsmith

That is more of a GitHub landing page than a readme.

> An effective README file needs to tell your audience what your project does, how to use it, and how they can help out.

The readme starts with an `a` image tag nested within a `p`.

[dcow]

Yep, the author of their readme is more interested in marketing their product than explaining how to get started using the project. It's honestly like the product person wrote the readme and not the engineers. And I consider that to be a pretty big red flag. At least, I'm not using the project any time soon because it's wasted my valuable time marketing to me instead to getting me straight to into the software. And it tracks me without my consent. Not a great readme...

0. There are tracking links in the readme?!? Ugh gross! Zzz... oh and btw: this readme tracks you even if you don't click links [vomit-emoji]. There's a tracking pixel loaded at the very end:

    <img referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=841c3402-679b-456d-b528-537480a57269" />

1. The Readme has images without accompanying text, so it can't be read in a text editor right after you've cloned the repo.

2. It's littered with useless information and noise when my main goal of reading the readme is to get up and running quickly with the project. The contributors section is one example (and I mean just look at the source and try not to laugh): I can click the contributors link in github if I want to see that stuff, and an authors/contributors file is a better spot for that info regardless (and really you spent time on a bot for that). Further, the "getting started in 100 seconds" image-only link is in the features section with no accompanying text and there's a getting started link in the contributors section, they kinda get lost in the noise.

3. There's just one link to the documentation and it's pretty far down. I'd recommend linking to it much much earlier so users who just want to get started aren't wading through all the marketing gifs.

4. I don't think this readme is GDPR or CCPA compliant... but IANAL.

Generally, a readme isn't a replacement for a marketing website especially for a product company. Maybe for a small open source entirely community driven effort most of their touchpoint will be a readme. But there's nothing organic about this readme, it's full of marketing fluff, tracking links, testimonials via contributor bubbles, and very little explanation of how app smith works, how you get started, example code, etc. Here's an example of a project with a really great readme: https://github.com/Lxtharia/minegrub-theme (it's just one of the other interesting links on HN today as well). And here's another one: https://github.com/stateful/runme.

Not trying to be too harsh, it's an okay middle of the range readme all things considered. But is it great? ..Meh.

[jamjamjamjamjam]

Putting a tracking pixel in a readme is a new one, wow. I would never want to clone that project in case I accidentally open the readme

[dcow]

Even just viewing it on GH loads the pixel.

[coobird]

My thought as well.

If every project started to make their README filled with HTML (gah, why does Markdown allow arbitrary HTML...), I'd end up crying on the CLI as I frantically search for how to build the project in a sea of <p>, <a> and <br/>s...

[atoav]

Quite frankly I was happy with the arbitrary html part more often than it annoyed me. E.g. when I had to add a table that was just slightly out of markdowns comfort zone (merged cells).

Those who read my readmes were always happy with the content and never complaines about the html.

[avgcorrection]

> gah, why does Markdown allow arbitrary HTML...

MarkDown is a misleading name.

[mgbmtl]

I love the "Steps: 1 - 2 - 3" image. It reminds me of the old Slashdot memes of:

  * Step 1: collect underpants
  * Step 2: ??
  * Step 3: Profit!