Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

How to write a great README

appsmith.com

Post reply on HN
Print view View original

21–30 of 56 posts

Re: How to write a great README

#21

Post by dcow »

drako999 wrote: post #2

Hey everyone, I'm a co-founder and CPO at Appsmith. I have used this article to share our experiences with writing a great README, and I think it would be beneficial to hear about everyone's experiences with what actually makes a README useful for an open source project. Would love your feedback on the topic. And of course, if you have any feedback on how we can make Appsmith's README more useful for you, please let…

One spot where your readme misses the mark: it can't be read outside of github (or some rendering engine). Markdown is supposed to be human readable. Instead you say "here's how app smith works" and then plop a big image. That doesn't help anybody understand what your project does by reading the readme. Images and diagrams are super helpful, but they should accompany thoughtful prose. This is also important as an accessibility consideration.

Next, contributors sections are dumb. Github is a better tool to use to view contributors (https://github.com/appsmithorg/appsmith/graphs/contributors). Other projects before github would have an authors and/or contributors file. I don't care about the contributors when I'm trying to understand how your project works, it's just shameless marketing in that position.

Finally, you have a "getting started in 100 seconds" image CTA in your features section. Doesn't make any sense to me and again there's no supporting text.

Overall I'd suggest focusing on improving your readme to be more useful and less of a marketing tool (it can still market its value lightly) and instead explain how the software works and how to get up and running with it.

Overall I'd score your readme 4/10.

Edit: here's a readme to compare/contrast with https://github.com/Lxtharia/minegrub-theme

Re: How to write a great README

#22

Post by lbhdc »

I feel like this has good intention, but I think it misses key information that should be in the readme.

Its really great to have a blurb about what the thing does, the big idea behind why it exists, and how it fits into the rest of the universe.

I also really want instructions for how to build the repository. It seems like that is really downplayed in this guide. I feel like that is misaligned with the target audience of those visiting the repository. I would rather sacrifice overview for instructions on how to use the thing.

Re: How to write a great README

#23

Post by drako999 »

lbhdc wrote: post #22

I feel like this has good intention, but I think it misses key information that should be in the readme. Its really great to have a blurb about what the thing does, the big idea behind why it exists, and how it fits into the rest of the universe. I also really want instructions for how to build the repository. It seems like that is really downplayed in this guide. I feel like that is misaligned with the target audien…

That was an intentional decision we took because we realised that the majority of users struggled to grasp the concept behind the project and how to use it. We didn't feel that we were ready to optimise for contributors yet :)

Good point about mentioning why it exists!

Re: How to write a great README

#24

Post by dcow »

avgcorrection wrote: post #16

> 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`.

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:
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.

Re: How to write a great README

#25

Post by lbhdc »

drako999 wrote: post #23
lbhdc wrote: post #22

I feel like this has good intention, but I think it misses key information that should be in the readme. Its really great to have a blurb about what the thing does, the big idea behind why it exists, and how it fits into the rest of the universe. I also really want instructions for how to build the repository. It seems like that is really downplayed in this guide. I feel like that is misaligned with the target audien…

That was an intentional decision we took because we realised that the majority of users struggled to grasp the concept behind the project and how to use it. We didn't feel that we were ready to optimise for contributors yet :) Good point about mentioning why it exists!

Totally fair, and I agree contributor docs generally make more sense to be in their own document. That is how I feel I have seen most repos handle those docs.

I was thinking less about contributors, and more about someone who just wants to use your project locally. Spin it up, try it out.

Scanning through the appsmith repo, I don't see any files that jump out to me as documentation on how to build and run it. So it seems I would need to dig through the build system to discover what runnable things are in there. I would probably have to look at some application code to figure out what kind of storage it wants to talk to and how to configure that.

That is a lot of work to give it a test drive. I assume this is to keep some moat for the saas offering, but that dx makes me less likely to consider exploring it to begin with.

Re: How to write a great README

#26

Post by hiatus »

rlnorthcutt wrote: post #3

This really stood out for me: 'We also think it is beneficial to show instead of tell wherever possible. We recommend using icons, images, and GIFs to keep it visually engaging and provide visual signposts — helping readers quickly navigate to the details that are important to them.' We know that things like bulleted lists, headings, and paragraph structure can have a massive impact on readability... and I think thos…

Are you really shilling for the project without disclosing your affiliation?

https://github.com/rlnorthcutt

Re: How to write a great README

#28

Post by hinnisdael »

distcs wrote: post #13

Since we are on this topic allow me to do an Ask HN comment here. Ask HN: What are some good Readmes you have found?

vidstack is very light on technical details but starts with a concise intro and a screenshot, as well as relevant links: https://github.com/vidstack/player

payload is well-structured in general: https://github.com/payloadcms/payload

nanostores starts out with an intro and telling code examples, followed by lots of technical details: https://github.com/nanostores/nanostores

Re: How to write a great README

#29

Post by m-hilgendorf »

rlnorthcutt wrote: post #3

This really stood out for me: 'We also think it is beneficial to show instead of tell wherever possible. We recommend using icons, images, and GIFs to keep it visually engaging and provide visual signposts — helping readers quickly navigate to the details that are important to them.' We know that things like bulleted lists, headings, and paragraph structure can have a massive impact on readability... and I think thos…

It can also make your project inaccessible if you rely too heavily on images.

Personally I don't like too many images in a README. It's not a SHOWME. That's for your product page.

Re: How to write a great README

#30

Post by bbno4 »

I have taken quite a few github projects to popularity and even written[0] about it

GitHub does not support centreing images so you have to use HTMl. One tip I'll add is to avoid as much HTMl as possible so if you're in the terminal you can actually read it

[0] https://skerritt.blog/make-popular-open-source-projects/

Post reply on HN