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!
Oldest comments (31)
I spend a lot of time in Postwoman's readme.
👽 A free, fast and beautiful API request builder used by 75k+ developers. https://hoppscotch.io
A free, fast and beautiful API request builder
Helps you create requests faster, saving precious time on development - Subscribe
Built with ❤︎ by
liyasthomas and
contributors
Chat: Telegram, Discord
Donate: GitHub Sponsors, Open Collective, Patreon, PayPal
Table of contents
Features✨
Methods:
GET- Retrieve information about the REST API resourceHEAD- Retrieve response headers identical to those of a GET request, but without the response body.POST- Create a REST API resourcePUT- Update a REST API resourceDELETE- Delete a REST…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?
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.
Wow that's a really great project!
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.
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!
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!
Awesome, thanks for sharing!
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?
getuikit.com
What do you like about the README?
I like the emoji in your titles, makes the README entertaining, well done 👍
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?
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!
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).
Goal well achieved 🎉
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
I love the GIF and link to live demo!!! That's an awesome concept. Thank you for sharing!
Very helpful—thank you for sharing!
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...
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.