How to write a great README | Hacker News Reader

How to write a great README

appsmith.com

170 pointsdrako99951 comments

Open articleView on HN

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

— 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)

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

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

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

MarkDown is a misleading name.

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.

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.

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

Even just viewing it on GH loads the pixel.

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!

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

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.

Please for the love of Cthulu remove that awful auto scroll from your homepage. It's practically unusable in a mobile webview.

Great article though!

+1 this is awful. I thought there was something wrong with my browser!

Thank you for the feedback! We'll fix it :)

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 generally have a “What Problem Does This Solve?” section in my READMEs.

https://github.com/LittleGreenViper/LGV_TZ_Lookup#what-probl...

https://github.com/RiftValleySoftware/RVS_Spinner#what-probl...

https://github.com/RiftValleySoftware/RVS_BlueThoth#what-pro...

https://github.com/RiftValleySoftware/RVS_PersistentPrefs#wh...

https://github.com/LittleGreenViper/LGV_MeetingServer#what-p...

etc.

Quick plug for makeareadme.com. I’ve always found it to be a good starting point for new projects.

https://www.makeareadme.com/

(clickable link!)

There's also this site which has a few different README templates: https://www.readme-templates.com/

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/

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

We really appreciate the shoutout on our Payload readme! We put a lot of effort into making it impactful and useful for our community.

Please include a screenshot if it's ever appropriate. You will save your visitors so much time!

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!

Love the write-up, I only have one question. What actual work were you procrastinating on by writing it ;)

Most likely, replying to user queries :)

There was no procrastination, this is called "content marketing."

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

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?

I think markdown reads very nicely in text form.

    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?

> riddled with ## and other junk

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.

My point is the ## provide structure and for me help to visually lay out the document, so I like reading markdown. To each their own.

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?

*A self proclaimed great README

I was gonna say... what's the benchmark they used to decide it was great? Did they win the best README award somewhere?

The culture of README

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

For a different take. Have a look at runme.dev

tl;dr although my first principle is good readme files.

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

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.

I totally agree - moderation is a good thing

I like using mermaid diagrams [1] in readme files and docs.

They're easier to read than plain text explanations for architectural layouts/customer journeys but easier to modify than images and GIFs.

Also natively supported in many flavours of markdown like Gitlab.

[1] https://github.com/mermaid-js/mermaid

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:

https://github.com/hbcondo/revenut-web#-workflow

But that diagram just renders as code for the same readme via GitHub Pages:

https://revenut.com

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

https://github.com/rlnorthcutt

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.

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.

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.

Reply on news.ycombinator.com