Here are the traditional best practices of how README files should look:
“The distribution should contain a file named README with a general overview of the package:
the name of the package;
the version number of the package, or refer to where in the package the version can be found;
a general description of what the package does;
a reference to the file INSTALL, which should in turn contain an explanation of the installation procedure;
a brief explanation of any unusual top-level directories or files, or other hints for readers to find their way around the source;
a reference to the file which contains the copying conditions. The GNU GPL, if used, should be in a file called COPYING. If the GNU LGPL is used, it should be in a file called COPYING.LESSER.”
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.
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...
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.
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.
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 :)
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.
I hate going to a project's GitHub page and seeing so much fluff and unnecessary or redundant information concealing the things that actually matter. If you want to show off, please do it on a separate website.
I want to know what it is, how to use it, how to build/install/deploy it, and any other specific requirements. Everything else can easily be moved to a wiki page (in moderation, no "wiki mazes"), or simply separate files. And for god's sake keep your gaudy emoji spam away from me.
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
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
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.
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?
So you download a folder or a zip file (anyone remember PKZIP?) and try to determine what its purpose or "application" is. I mean, there is almost certainly an app in here, right?
So, why have I downloaded this .zip file? Not sure, had an interesting title, and yeah, let's see what the author has to say. First stop: README.txt
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 those visual touches go even further.
Of course, just using icons doesn't do anything (And can make it worse), but if they are relevant, then it adds another layer of data. +1 on images and Gifs - I find it much easier to evaluate a project if I have some idea of what it looks like (Assumign it has a UI).
My apologies - it was a quick comment between calls :D
In full disclosure, I'm the Head of DevRel at Appsmith. I didn't write this article, or contribute to it.
That being said, I do think its helpful, and I like the fact that other projects' READMEs are noted as good examples too.
To me, too much use of icons, images, and GIFs sort of looks spammy. But I think there's a middle-ground where you just use images to help explain the architecture and a GIF to show a demo but you don't go overboard with it all.
True - but not every project is a product. I run across open source projects all the time where the README is the product page. In those cases, I appreciate some images which can help me figure out if I want to try it out.
Otherwise, I have to install or set it up just to preview it, and I will personally not do that most of the time. So, I appreciate some images when they help me evaluate the project.
Same here, I like Draw.io but just did a sequence diagram showing a Stripe integration with actors, activations and notes in a few lines of Mermaid markdown on a GitHub readme:
“The distribution should contain a file named README with a general overview of the package:
the name of the package;
the version number of the package, or refer to where in the package the version can be found;
a general description of what the package does;
a reference to the file INSTALL, which should in turn contain an explanation of the installation procedure;
a brief explanation of any unusual top-level directories or files, or other hints for readers to find their way around the source;
a reference to the file which contains the copying conditions. The GNU GPL, if used, should be in a file called COPYING. If the GNU LGPL is used, it should be in a file called COPYING.LESSER.”
— GNU Coding Standards, https://www.gnu.org/prep/standards/html_node/Releases.html#i... (July 1, 2021)
“Good things to have in the README include:
1. A brief description of the project.
2. A pointer to the project website (if it has one)
3. Notes on the developer's build environment and potential portability problems.
4. A roadmap describing important files and subdirectories.
5. Either build/installation instructions or a pointer to a file containing same (usually INSTALL).
6. Either a maintainers/credits list or a pointer to a file containing same (usually CREDITS).
7. Either recent project news or a pointer to a file containing same (usually NEWS).”
— Software Release Practice HOWTO, https://tldp.org/HOWTO/Software-Release-Practice-HOWTO/distp... (Revision 4.1)