DEV Community

Stephanie Morillo
Stephanie Morillo

Posted on • Updated on

What are some examples of open-source projects with great READMEs?

Hey DEV Community👋🏽

What are some examples of open-source projects that have great READMEs? Specifically, projects that:

  • Describe what the project is
  • Provide installation instructions and other documentation
  • Include instructions for contributing to the project

(Other criteria are outlined in this blog post, "How to Write a Great README")

In addition to providing examples, what do you think makes these READMEs effective? Share your thoughts in the comments!

Discussion (34)

Collapse
ijlee2 profile image
Isaac Lee • Edited on

Hi, there! 👋

I created ember-container-query and am happy with how its README turned out. I like it for these reasons:

  • Continuous integration badges to deliver confidence
  • Quick demo GIF
  • 1-line installation
  • List of practical applications
  • <summary> tags to hide details and not overwhelm first-time visitors

GitHub logo ijlee2 / ember-container-query

Make container queries that harness the power of Ember Octane.

This project uses GitHub Actions for continuous integration. This project is using Percy.io for visual regression testing.

ember-container-query

Make container queries that harness the power of Ember Octane.

Demo of ember-container-query

Open the demo app to see ember-container-query in action. (There's even a 404 page!)

Installation

ember install ember-container-query
Use FastBoot? ⚠️

This addon uses nullish coalescing operator ??. If you use FastBoot (with Node < v14.0) and only support browsers that natively support ??, you will run into a build error:

/var/folders/2z/93zyyhx13rs879qr8rzyxrb40000gn/T/broccoli-689520dxo26a682Mz/out-529-broccoli_merge_trees/assets/vendor.js:121232
  return this.args.features ?? {};
                             ^
SyntaxError: Unexpected token '?'

To prevent this, please make sure to add node: 'current' to your config/targets.js file.

'use strict';
const browsers = [ ... ];
module.exports = {
  browsers,
  node: 'current'
};

Applications

Where can you use container queries? Here are real-life (and some theoretical) applications!

Create reusable components that are independent of screen size ♻️
  1. Components form a core of an Ember app. We love components!

  2. With…

Collapse
liyasthomas profile image
Liyas Thomas • Edited on

I spend a lot of time in Postwoman's readme.

GitHub logo hoppscotch / hoppscotch

👽 A free, fast and beautiful API request builder used by 75k+ developers. https://hoppscotch.io

hoppscotch.io logo

A free, fast and beautiful API request builder

Helps you create requests faster, saving precious time on development - Subscribe

Travis Build Status GitHub release Website Contributions welcome Financial Contributors on Open Collective Donate on PayPal Chat on Telegram Chat on Discord Tweet


Built with ❤︎ by
liyasthomas and
contributors




Chat: Telegram, Discord

Donate: GitHub Sponsors, Open Collective, Patreon, PayPal

Screenshot1
Table of contents

Features

❤️ Lightweight: Crafted with minimalistic UI design.

⚡️ Fast: Send requests and get/copy responses in real-time.

Methods:

  • GET - Retrieve information about the REST API resource
  • HEAD - Retrieve response headers identical to those of a GET request, but without the response body.
  • POST - Create a REST API resource
  • PUT - Update a REST API resource
  • DELETE - Delete a REST…




Collapse
sarensw profile image
Stephan Arenswald

I do like READMEs that have this hero-like header part as shown in this example. It looks professional and I don't have the feeling that this is just made for experts.

Collapse
radiomorillo profile image
Stephanie Morillo Author

Thanks for sharing, Liyas—indeed, it's very detailed.

Did you take inspiration from other projects? How did you cmake the decision to structure your README the way you did?

Collapse
liyasthomas profile image
Liyas Thomas

I remember finding a public gist which had most of the sections for a README boilerplate. I don't have the link to it with me now.

Collapse
goxr3plus profile image
GOXR3PLUS STUDIO

Wow that's a really great project!

Collapse
maheshkay profile image
Mahesh K

Not in context with readme but if you check how Kent Dodds writes his issues and also guidelines for newbies, it's definitely inspiring in context of knowledge-transfer. I follow him to see how he transfers his learning to newbies and others. His github and twitter activity on that part is amazing.

Collapse
daviddalbusco profile image
David Dal Busco

I like the emoji in your titles, makes the README entertaining, well done 👍

Collapse
n8chz profile image
Lorraine Lee

I can't off the top of my head think of a specific project with a great README, but a platform I associate with great READMEs is npmjs.com. The convention there seems to be "lead by example." It seems to me anyway that usually the first item in the doc for a node module is an example instantiation of call of whatever it is. Contrast this with UNIX man pages, where it's almost my reflex to press G (go to bottom of man page) which is where there's usually one or more usage examples, above which is an exhaustive list of all possible command switches or function parameters. (cw pun ahead) You might say the npmjs.com philosophy is "lead by example" while the UNIX man pages philosophy is "bury the lede."

Collapse
roywj profile image
Roy

I made one recently. It's for my icon open-source project called Neu Icons. At the beginning of writing the README, I found many issues about how I can make it visually as I want. But time goes by I learned how the markdown works and so on. And now I am pretty happy with it.

The importance of writing README for me have these aspects:

  • Describe what the project is for
  • Clear information about how to use it
  • Write as detail as possible, it will help people to understand the project, a lot
  • Give some notes if some features are under construction
  • Give some credits to people who helped to bring the project live to the community
Collapse
radiomorillo profile image
Stephanie Morillo Author

Good tips, thanks Roy!

Collapse
daviddalbusco profile image
David Dal Busco

Having a monorepo like ours, didn't actually made it easy to compose a single entry README. You can't for example display an "installation guide" if the repo contains many installation guides.

After some thoughts, I went for an introduction and a list of all its apps, components, functions etc. It also displays a link to the developer documentation.

Any ideas of improvements?

Collapse
radiomorillo profile image
Stephanie Morillo Author

Hey David—when I was on the Bundler core team (now a part of RubyGems), we had several Markdown files for things like contributing guidelines to installation instructions. In our case, the documentation site was its own repo, but we linked out to it from the main repo.

It seems you're doing this now and I really like how organized all the various component links are displayed. I'd be interested to hear from others who have a similar use case!

Collapse
daviddalbusco profile image
David Dal Busco

Thanks Stephanie for your feedback 🙏 I am really happy to hear that the organization of this entry readme file looks alright. It took a bit of time to figure it out. We even only added recently the CHANGELOGs uri, thanks to a PR of a contributor (Roy).

Collapse
i8sumpi profile image
Kira L

My programming language, Blue, doesn't use the README, but it does have a pretty detailed documentation page: kiraprograms.com/blue/help.html. It describes the project on the main page: kiraprograms.com/blue/help.html, and it doesn't have instructions for installation because it's 100% in the browser. I spent over half of the time just working on the documentation, which, in theory, could also be used as a tutorial. It's probably not much compared to massive projects made by teams of programmers, but it took a while consitering that I did it totally on my own.

Collapse
radiomorillo profile image
Stephanie Morillo Author

Thanks for sharing! Since READMEs are generally associated with projects that are hosted on sites like GitHub, I'm curious—is Blue on GitHub? Do you take contributions from external collaborators? I'd love to hear how you made the decisions to share your project this way!

Collapse
i8sumpi profile image
Kira L

It does have a GitHub repository but the README there isn't very great because I made the syntax highlighting on my own, and Blue is not a language in GitHub's syntax highliting. It isn't a very big project so I only did it on my own. Since it's small, I am happy to take other people's suggestions, but don't need other people to actually write more code unless I know them personally. You can see the GitHub repository at github.com/i8sumPi/blue!

Thread Thread
radiomorillo profile image
Stephanie Morillo Author

Awesome, thanks for sharing!

Collapse
delta456 profile image
Swastik Baranwal

I have spent a lot of time on this one. I hope you can give feedbacks on this. (I find my README great btw c:)

Collapse
radiomorillo profile image
Stephanie Morillo Author

Thanks for sharing!

How did you come up with your README format? And regarding contributions—do you get them frequently? Do they need to be formatted or structured in a particular way? What about issues?

Collapse
milantenk profile image
Milán Tenk

I made recently one of my hobby projects open source. It is an Angular component, you can check its README here:
github.com/milantenk/ngx-interacti...

What I held important to have

  • a gif, which gives a rough overview about the component
  • a live demo link, which can give a hands-on experience
  • description about the usage of the component
  • a short summary, how to get started with the development of the library
Collapse
radiomorillo profile image
Stephanie Morillo Author

I love the GIF and link to live demo!!! That's an awesome concept. Thank you for sharing!

radiomorillo profile image
Stephanie Morillo Author

Very helpful—thank you for sharing!

daviddalbusco profile image
David Dal Busco

Goal well achieved 🎉

Collapse
koistya profile image
Konstantin Tarkus

Additionally, it helps to have a "Tech Stack" section somewhere at the top near "Getting Started":

github.com/kriasoft/nodejs-api-sta...
github.com/kriasoft/react-firebase...

Collapse
radiomorillo profile image
Stephanie Morillo Author

Agreed. These READMEs are excellent!

I really like how they outline the repo structure and the requirements before installing the software. I'm also a huge fan of the contributing section and how they guide users through each next step.

Collapse
charanjitsingh profile image
Charanjit Singh

I'd recommend slateJS . It's WYSIWYG editor with which you can build even Google Docs. Have a look.

Collapse
radiomorillo profile image
Stephanie Morillo Author

Is there a README for this project? What makes it a good README?

Collapse
sakshatshinde profile image
Sakshat

This one's mine, pretty simple but I like putting in diagrams/images.

GitHub logo sakshatshinde / Plei

A game launcher with no bloat

Plei

A game launcher with no bloat

forthebadge made-with-python

HitCount contributions welcome License: GPL v3

Image

This project is ready for the launchers given below!

  • Steam
  • Origin
  • Epic Games Launcher
  • Uplay
  • Standalone Games

Why is this a thing?

As new game launchers came into being it increasingly got annoying to keep track of all the games over different stores/platform. I wanted to make a unified front where users can access all their games, including the one with no launchers. The goal behind this launcher is to be simple, minimilistic and bloat-free


How to install?

  • Download the latest version from releases
  • Run the setup.exe
  • Run Plei.exe (May require admin privileages if installed in C:// drive)

How to install? (for devs)

This installation assumed you have python 3.X installed. Get python here

  • Download Plei and extract it to your desired location
  • Run the following command

pip install -r requirements.txt

  • It might error out on "steamfiles" install. To fix this change your…
Collapse
aanandmadhav profile image
Aanand Madhav

getuikit.com

Collapse
radiomorillo profile image
Stephanie Morillo Author

What do you like about the README?