If you’ve ever visited a GitHub repository, you’ve definitely seen a README document.
They function as a sort of entryway to a development project and supply all the information a visitor needs to understand and contribute to it.
In this guide, we’ll tell you exactly what a README document is, why it’s important, and how to create one that’s going to help your project.
Let’s start with a proper definition.
What Are README Docs
README files are an essential part of working on development projects on GitHub while providing a starting point for the documentation.
Therefore, to understand what README files are and what they do, we must first understand the platform where you will be encountering them.
GitHub is a cloud-based platform for the management and safekeeping of code. Â
It enables developers to work on development projects together, no matter where in the world they are, and control how the code changes and evolves over time.
Now, GitHub is a for-profit company. It offers private hosting spaces for developers to collaborate and build more efficiently.
However, anyone can sign up for an account and host a free development project, making the platform very popular for open-source projects.
For example, take a look at the space dedicated to WordPress, the open-source content management system used by almost half of all websites around the world.
There are more than fifty million open-source projects like this one on GitHub.
Users who browse them need a way to get informed about what the individual projects are about and how they work.
And that’s where README files come in.
These simple files contain the basic information about a piece of software, code, or game, so that a newcomer to the project can quickly understand what the project is about and how they can contribute.
Let’s stick with our WordPress example and have a look at what its README file looks like.
As you can see, the document contains a basic description of the software and explains how to work with it.
There’s a list of requirements that need to be fulfilled to work with the code and a set of instructions for completing basic tasks.
The document ends with a list of credentials the user will need to access the project.
When you create a new repository in GitHub, you’ll get the option of a default README file because this is such an integral part of any such repository.
The default README file is written in Markdown, a simple markup language that enables these files to be easily converted into text for user consumption.
You’ll have no problem spotting this document in a GitHub repository because it’s usually titled as just “README” with an .md extension.
README files are what visitors to a repository check out first, in order to get informed on the basics of the project.
They’re usually very simple but can help your project get the attention it deserves, which is why you should definitely take the time to write a quality README document for your project.
Why Are README Docs Important
In the last section, we talked about how README files provide basic information about a development project to help visitors orient themselves and understand what you're building.
But the importance of this document goes beyond just defining a development project. It can be useful to multiple kinds of people that come into contact with your repository.
This includes:
- Fellow developers
- End users
- Potential employers
- You, as the owner of the project
So let’s see how README files can benefit each of these groups.
Fellow developers coming to your repository will probably look at your README document before they do anything else.
Aside from a description of the project, the README also commonly contains instructions for launching the software and the basics for working with it.
Developers coming to your repository won’t automatically know what you’re working on and how to install or modify the software.
The README file provides them with this information so that they can jump straight into working with the code.
Similarly, end users access the README file to learn about the project and discover what its uses are to decide if your software is the right tool for completing a task they have in mind.
For example, have a look at how this README for a software project called Size Limit does a great job of explaining the use cases for this performance budget tool.
Every use case also has a set of instructions attached to it, so that users can quickly deploy it for their work.
In this way, the README functions as a promotional document that helps end users connect with your project.
Finally, you yourself can benefit from a quality README file in more than one way.
For example, let’s say you start working on a development project but have to abandon it for some reason, and you can only return to it after some time.
In that case, you might have already forgotten how the code works, making it hard to pick up where you left off.
Your README document can then serve as a reminder of the basics of the code and the idea you wanted to implement when you first started building the software.
Also, since GitHub profiles and repositories are a common element in a developer's resume, README documents can play a vital role in helping a future employer understand what kinds of projects you have been working on in GitHub.
All you have to do is include a link to your work in your resume or LinkedIn profile and then have README files ready for employers or recruiters to inspect.
In conclusion, since README documents explain a project and provide instructions on working with the code, they are a type of technical document that’s very useful to anyone accessing a repository for that project on GitHub.
Their importance lies in the fact that they can help newcomers understand what you’re working on and help developers stay on top of their projects.
What Makes a Great README Doc
From all that was said thus far, it should be becoming clear that README docs work best when they are concise to provide a quick intro to the project yet informative enough to allow anyone approaching the project to work with the code confidently and successfully.
But it’s about more than just providing instructions. If you want people to form a genuine interest in your project, you’re going to need to explain to them why your project is worth their time.
Pedro Sanders, the founder of Fonoster, the open-source Twilio alternative that’s getting a lot of traction on GitHub, suggests wowing visitors to your repository with a call to action and a unique value proposition to motivate them to join your project.
In the case of Fonoster, both elements are given in a simple and elegant way, right at the top of the README document, helping readers connect to the project and start seeing the value it can bring.
Our point here is that a good README has to have a degree of emotion to it. You need to show visitors that you’re excited about the project and get them hyped too.
Once you have your audience hooked, the rest of the document should explain how the software works in a concise and very clear way, meaning you can substitute emotion for a more objective, instructional style.
Here’s a great example from Create Go App CLI.
Notice that these installation instructions are light on text and provide every line of code the user will need to start the software.
There’s no embellishment, just clear-cut information to provide the incoming developer with everything they need to work.
Finally, make sure that the README is frequently updated and checked for accuracy.
It definitely won’t serve you to have a README document that doesn’t reflect the current state of the software because users might get an unwanted result from following the document’s instructions.
If that happens, they might come to the conclusion that the software is low-quality or full of bugs and decide not to contribute to it or use it.
An added benefit is that by frequently updating the README, you’re also showing visitors that the software is alive and kicking.
This is important because no one wants to contribute to a project that seems dead and forgotten.
That’s why project owners sometimes start their README with a section on recent activity so that contributors and users can track what’s going on with the software in real time.
All in all, a great README document provides visitors with accurate and up-to-date information to help them work with the software, but it’s also successful in conveying excitement and value to motivate others to join the project.
What Should Be Included in a README Doc
Now that we’ve established what a great README document should accomplish, let’s see which elements it should include to attract and educate users and contributors.
It’s a good idea to start things off with a table of contents, especially if your README is on the longer side.
A table of contents gives visitors an overview of the entire document (and project) and can be extremely useful in helping them navigate the README.
No introduction is complete without an overview or description of the project to illuminate the readers on what the project is about.
This example from Day 8 is a good case in point. It provides a two-sentence description of the project and gives a little background on its history.
Equally important, the authors explain the project's tactical advantage and unique value propsition (we discussed the importance of this in the last section).
Your overview can also contain usage cases, practical implementations, and other information that explains to the reader why this project is valuable.
With the introductions out of the way, it’s time to get down to the code. In this part of the README, two sections are of paramount importance.
The first one is the installation/quick start/setup guide. Newcomers to the project will need an entry point to the software and this is your chance to provide it.
The second element you shouldn’t do without are code examples. Developers are notorious for their reluctance to read too much explanatory text.
They’re much more interested in playing with the code and learning by doing.
Providing code examples enables visitors to see how the code works in real environments instead of just theory.
It also allows developers to try out the code themselves, which might pique their interest to continue using it.
Finally, the last part of your README document should be reserved for a couple of formalities.
This is where you establish who holds the rights to the project (the license) and acknowledge the hard work of people who contributed to it.
If no license is mentioned, that means that all rights are reserved, and the user needs to obtain one from the authors.
Otherwise, the licensing will be explained in the README and usually link to a separate document that holds the necessary information.
These are the essential sections of a README document, but you can definitely add more information if you need to.
Check out this template to find more sections to add to your README.
Conclusion
We hope this article has provided you with all the information you need to understand the value of README documents and their key role in attracting attention to a development project on GitHub.
By learning the meaning and importance of this important document, as well as the basics of creating one, you’ll definitely be able to represent your projects better and motivate people to contribute to them.
‍
