Arguably the single most important piece of documentation for any open source project is the README. A good README not only informs people what the project does and who it is for but also how they use and contribute to it.
If you write a README without sufficient explanation of what your project does or how people can use it then it pretty much defeats the purpose of being open source as other developers are less likely to engage with or contribute towards it.
TL;DR - Too long? Skip to the end and use my template.
What is a README?
Essentially a README is a single text file (.txt or .md) that acts as the one-stop shop documentation for a project or directory. It is usually the most visible piece of documentation and landing page for most open source projects. Even a README file's name in all-caps is designed to catch your reader's attention and ensure it is the first thing they read.
There's evidence that READMEs date back as far as the 1970s. The oldest example I could find was this README for DEC's PDP-10 computer which is dated 27th November 1974. Although the origin of the name README is disputed, the two most popular theories are:
Programmers of the original mainframe computers which came with punch cards, would leave a stack of paper instructions with “READ ME!” written across the front.
The name is a nod to Lewis Carroll's Alice in Wonderland in which the main character Alice finds a bottle of potion labelled “DRINK ME” and cake labelled "EAT ME" which make her change in size.
What should you include in a README?
Ok, so what should an awesome README file contain? As a starting point, I would recommend you include the following key things:
1. Name the thing
Don't forget to give your project or feature a name. There are a surprising number of projects on GitHub that don't have a name.
2. An introduction or summary
Write a short two or three line introduction explaining what your project does and who it is for. Also leave out headings like 'Introduction', 'Summary' or 'Overview' - it's obvious this is an introduction.
3. Prerequisites
Immediately after your introduction add a section titled listing any prerequisite knowledge or tools anyone who wants to use the project might need before they begin. For example, if it runs on the latest version of Python, tell them to install Python. Here's an example:
Prerequisites
Before you continue, ensure you have met the following requirements:
* You have installed the latest version of Ruby.
* You are using a Linux or Mac OS machine. Windows is not currently supported.
* You have a basic understanding of graph theory.
4. How to install the thing
Provide installation steps! It's amazing how many projects I've come across that only provide basic usage instructions and expect you to magically know how to install it. Make sure to break the installation down into numbered steps if it requires multiple steps.
5. How to use the thing
Add steps for how to use the project once the user has installed it. Make sure to include usage examples and a reference explaining command options or flags if you think they will be helpful. If you have more advanced documentation in a separate file or site, link to this from here.
6. How to contribute to the thing
Provide steps for contributing to the project. Alternatively you might want to create a contributor's guide in a separate file and link to this from your README if you want people to read it before contributing pull requests to your project.
7. Add contributors
Credit any contributors who have helped with the project in an author section. It's a nice way to make open source feel like a team effort and acknowledges everyone who has taken the time to contribute.
8. Add acknowledgements
Similarly, if you have used anyone else's work (code, designs, images etc) that has a copyright that requires acknowledgement, you might want to add that here. You can also acknowledge any other developers or institutions who helped with the project.
9. Contact information
You might not want to do this is you're an extremely private person but if someone has questions, wants to collaborate with you or is impressed enough with your project to offer you a job opportunity, it makes sense to have your contact details front and centre.
10. Add licence information
You definitely want to include licence information if applicable. Startups and other companies who rely on third-party software are unlikely to be able to use your project unless you provide this. Check out choosealicense.com or opensource.org for a list of licences you may be able to use.
Add flare to your README 🔥
If you really want to make your README stand out and look visually appealing you can do things like:
Add a logo: If your project has a logo, add this at the top of your README. Branding makes a project looks more professional and helps people remember it.
Add badges or shields: You can add badges and shields to reflect the current status of the project, the licence it uses and if any dependencies it uses are up-to-date. Plus they look pretty cool! You can find a list of badges or design your own at Shields.io.
Add screenshots: Sometimes a simple screenshot or set of screenshots can say far more than a thousand words. Be warned though, if you do use screenshots you will need to update them each time you update your project.
Use emojis?: A lot of projects seem to use emojis these days, although it’s up to you whether you want to use them. They can be a good way to inject a bit colour and humour into your README and makes the project feel a bit more human.
If you're using All Contributors to acknowledge contributions, you could use their emoji key to denote different contributions types:
* 🐛 for raising a bug
* 💻 for submitting code
* 📖 for docs contributions etc.
This is what GitHub badges or shields look like for reference (No doubt you've seen them before!):
My template
I've created a template that covers most of the recommendations made in this post. Feel free to fork the repository, make suggestions to improve it or customize it for your own purposes! You can find my template on GitHub here.
Resources
If you want more advice on READMEs, I'd also recommend these resources:
Daniel Beck's talk 'Write the Readable' from Write the Docs in 2016.
Lorna Jane Mitchell's talk 'Github as a landing page' from API the Docs 2019.
Check out Franck Abgrall's README generator.
Top comments (46)
Emojis is a matter of taste.
You are missing two important things:
Agreed re:emojis and logo! Have made an edit. Thanks!
The risk of adding a TOC is you push all the important information like the intro/project summary etc further down. I’d only really use one if your README is incredibly long (or I’d move some of that content into another file).
I think if you've got enough info to warrant a TOC, that should follow the initial intro section of the document that describes what the thing is, etc.. AND, that's probably a good time to also think about splitting it into multiple files, ie: instead of a contributors section, a separate contributors.md file, etc.
+1 this is what I did. Once it gets to a certain length ah... you kind of need one up top.
There's also this great tool to generate a README based on your package.json 😄 I use it for all of my projects
That's very specific for Github projects that fit in a fairly narrow window. I know the point of a template is that you use it as a starting point, but for most of the stuff I do, I'd be deleting more than half the template every time.
That's the one linked at the bottom (in the resources) 😉
Aaah sorry I missed it ! Glad you did, it's super useful. Great article James 😄
Thanks for your recommendation, it seems easy and helpful to work 💪
Take a cue from those same old school manuals you reference as to what they include. Who cares about badges and emojis. That's marketing. Put marketing on your site. This is about getting shit done
Most non obvious projects should have a glossary of terms. These are business or non-standard technical terms you need to understand to make sense of the code.
You should also probably have an architectural overview. Charts (plantuml + graphviz ftw there). Enough to convey a high level understanding of how the darn thing is built. There is nowhere better for this.
Justifications for potentially controversial architectural decisions can probably go into issue and or discussions but at least link em!
I've also found a short FAQ section to be a good idea here.
Justifications of potentially controversial decisions as well, as there is simply no better place for them and its important for people to understand.
Thanks for the feedback!
I honestly wouldn't advise including a glossary in a README. Make it a separate file or have it on your documentation site. You can add links to definitions if you really need to.
A simple high-level architecture diagram isn't a bad idea if you want to mess around with Graphviz but anything more complex I'd keep to a separate doc.
If you need an FAQ you should be asking, why aren't these questions answered in my README?
But listen to what you yourself are saying James. You - very correctly in my opinion - start of with the historical perspective, but now are recommending discarding the lessons that were learned in how to compose those very documents. That might make sense, sure, but you'd agree I hope that it would at least need to be justified.
What is the purpose of a README? It should be everything you need to get started in working with the project, right?
And more specifically, the huge benefit over separate docs is that it lives alongside your code and can change in tandem. So if an important architectural concern changes but the related docs do not, you can see and comment on it right in the same pull request! So maybe, once your project stabilizes you can move that stuff to a different linked document but frankly most projects will never get to that level of stable.
As for FAQ... Well if you put it into the README then it *would*be answered there 😉, but I take your point. The reason I end up having it anyways is as a concession to both suboptimal organization (shit, this is important but there's no obvious section for it), and to people who are in a hurry to get stuff done and don't read all the docs.
I'm not saying to discard anything. The early READMEs were absolutely terrible. If there was a lesson to be learned it would be: Do not copy the format of the example README from 1974 😂
I get your point re: it's good to have stuff in one place but if you're using a docs-as-code approach then your docs live alongside the code anyway so all of your docs files will be updated as you update the code.
I guess it's personal preference re: FAQs but for me, they don't belong in a README. Relevant article here: FAQs Are A Code Smell.
I mean the people that created the stuff a lot of our works is based on surely had some aspects of it figured out :)
And yeah I agree an FAQ is absolutely a smell, it's just also often a reasonable concession for when you don't have resources for a more elegant solution.
This is a great (and necessary) introduction to writing helpful READMEs.
The only thing I would add is that I've found GIFs to be even more helpful than screenshots for showing off the functionality of your project.
I have used GIFs in the past (and yes, can be a great way to highlight functionality). You just need to mindful that you’ll need to update them if anything visual changes in your project (like with screenshots).
I use this module github.com/kefranabg/readme-md-gen.... It's easy, straight forward and generates beautiful readme within seconds.
Hey Shad, thanks! Yeah, that’s the last link I put in the resources (see bottom of the page) :)
My bad, missed it. Good article bdw.
Dude, your profile pic is awesome.
Haha thanks!
Contributors list will be great too,i have created an opensource app which can be used to create markdown ,it allows to reuse commonly used items such as licence or contributors list.
markdownapp.now.sh/
I feel like screenshots are a little bit overlooked in repositories. I especially find gif crops that display core features very useful. They are focused and attractive while it takes only a few seconds to grasp context. When applicable screenshots and gifs can provide a nice motivation to drive people into the project.
I've made an open source project to generate README section recommendations based on the most popular repositories for each language on GitHub. Would love yo get your thoughts and contributions: hpbl.github.io/WRITEME
Sure. Is there a repo link so I can submit a pull request or is it private?
Sorry for the delayed response, but yes: github.com/hpbl/writeme
Or you could just follow the standard-readme specs: github.com/RichardLitt/standard-re...
Cool, I didn’t even know this was a thing!
Nice read thanks!
At minimum I try to include these sections:
Any extended advice on what legal to put in a readme? Especially wondering about the situations where you do not want anyone to be using the code. "closed source" if you will.
This is a great question (you also reminded me to add choosealicense.com to the licenses section!) but I don't have an answer for you I'm afraid and I don't want to give you bad advice.
However you may find some useful info in this chapter on Non-Open Source Licenses and The Legal Side of Open Source. Hope that helps!
Wow, great resource nonetheless. You've pointed me towards a "Classic Proprietary License" for projects that contain open source code but is not licensable. Thanks for the great article and reply!
You lost me at Ruby.
You had me at Hello.
Missed opportunity... You had me at 'echo: hello world'
I'm happy to see good tips to add with my already good practices 😜
Thank's for this post.
Very accurate all the info. Maybe I should re-edit all my Readme based in this info. Thanks 👍