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 us know!
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.
Also: Don't use Markdown. Yes, it's "human-readable," but it's full of code text and there are almost no stand-alone VIEWERS for it.
The rampant use of Markdown while there's a lack of viewers for it is baffling. And no, I don't count editors in which you can invoke a "preview" of the Markdown. Why publish in a format that must be loaded into an editor and then "previewed?"
You might as well just use plain text, since the reader is just going to be seeing the raw text of the file anyway.
Or have stand-alone viewers (not editors) for Markdown proliferated since I last checked a couple years ago?
Title
===
Summary of the page
# H1 Intersting Topic
The most important part of [1] is...
## H2 What others say
> Quote from somebody. Callout something.
And then it's implemented like:
```
// this code is a demonstration of how to query foo
func foo() {
does_thing();
}
```
# Conclusion
You should use markdown to structure your documents.
[1]: https://example.com
I said yes, you can read it. But I also noted that it's riddled with ## and other junk that doesn't do anything beneficial because you're seeing plain text. So why have detracting, non-informational characters in there?
I'd argue in favor of those. A competent text editor (let's say no older than 40 years old) can highlight and/or render that. When using base markdown, those things add structure to the document. I'd much rather see a markdown file with basics like headers and code sections (which are usually highlighted correctly) than a raw .txt file.
however I think your argument goes doubly hard when dealing with these more advanced html integrated readmes. The md file of the example readme is not well readable when opened in a text file to me- and there's actually very little content there! I prefer a more minimal approach where opening the .md file gives me the information I need, and opening it in a rendered environment gets me some niceties (perhaps you've got badges with coverage or versions nrs idk). But it should work in both.
"A competent text editor (let's say no older than 40 years old) can highlight and/or render that"
But I'm not EDITING them. I just want to double-click on it and read the document, rendered properly. I do not want to have to open it in an editing environment and then invoke a preview (which often takes double the screen space). Again, WTF is up with the lack of lightweight, dedicated Markdown viewers?
I don't agree that stuff like ## and `` all over the place is eye-catching and attractive formatting. It's absurdly regressive. At that point, why not just use RTF, for which there are built-in viewers in the dominant OSes? Or if you really want plain text, use indentation, spacing, and capitals to organize the document.
If OSes' default viewers (like Notepad in Windows or Preview on the Mac) would render Markdown, I'd be fine with it. But they don't, and if they haven't added it yet, it doesn't seem that they will.
Great guide. One thing that seems to be missing is something I see in a lot of README's: a list of the core tech stack being used in the repo. Good examples here https://github.com/undb-xyz/undb#-tech-stack and here https://github.com/steven-tey/novel#tech-stack. Did you already consider adding this as part of the guide and decide against it, or was it just not something you thought to add?
