The Observatory

Authored by: Eric Crooks, Senior Software Engineer

In this article, you will learn about the README file, why it’s important to have one and how to write a detailed one.

There is no single correct way to write a README file. README files vary from project to project. However, a detailed README file removes ambiguities so developers can get started quickly without issues.

Note: The example code blocks shown in this article are strictly examples. They do not work.

The Purpose of the README File

When developers search websites like GitHub for software projects, the first thing they see when viewing a project is the project’s README file. This file tells developers everything they need to know about the project — how to use it, how to install it, how to test it, etc. It is the very first documentation page for a project.

When a project doesn’t have a README file, it means nobody can know anything about it unless they dive into its code to figure out how it works. Most of the time, developers aren’t willing to do this, so they search for something else — something with documentation.

Example Situation

You’re working on a project and you’ve pushed it to GitHub. You view your project on GitHub and you notice you still need a README file.

This being said, let’s write a README file!

Write the README File

The README file is the very first documentation page that developers see when they view your project. Having a README file doesn’t necessarily mean your project is ready to be used by developers. You need a detailed README file — one that includes useful information like the following (this is not a definitive list):

• How to use your project
• How to install your project for development purposes
• What problems your project solves
• Contributing guidelines
• Licensing
• Features included (optional)
• Technologies used (optional)

So how do you make your README file meet criteria like the above without drowning developers with paragraphs? First, you’ll want to split your README file into sections like the following:

• Name/description
• Quickstart
• Installation
• API (if your project exposes APIs)
• Why use this project?
• Contributing guidelines
• License
• Optionally a Features and Technologies section

Let’s go over each of these sections more in-depth as a series of steps using the following project for context:

• Project name: Searchable
• Project description: A JavaScript library that allows you to make arrays searchable using search terms.

Step 1: Write the Name and Description

This section should state your project’s name and provide a clear and concise description. For example:

Step 2: Write the Quickstart Guide

This section is for developers who already know what they’re doing and want to dive right in (typically wanting to just copy and paste code). This section should show exactly how to get started quickly. For example:

Make sure you test that your quickstart guide works. If your quickstart guide doesn’t work, it can leave developers frustrated.

Step 3: Write the Installation Steps

If you plan for your project to be worked on by other developers, then include all steps required to install your project on a machine. Think of this section as a teaching point to a new developer. When you teach, you start from the beginning. Using Searchable, its installation section could look like:

A more complex project could have an installation section that looks like this:

The key takeaway here is that when you provide installation steps, you must start from the beginning and assume the developer has no working knowledge of your project and their machine doesn’t have all of the technologies your project requires.

Step 4: Explain What APIs In Your Project Are Exposed

If your project is something that developers can interact with, then show them how that’s possible. In Searchable’s case, there are two APIs that are exposed for developers to interact with:

• Searchable.makeSearchable()
• Searchable.search()

Note: “Exposed” means you are allowing developers access to your project’s internal code through an interface (an API). They don’t necessarily need to see all of the internal code to be able to access it. Basically, you are saying, “Here’s my project, and here’s how you can interact with it.”

An example of an API section for Searchable could look like the following:

Show how the APIs work in action by providing example code. Also, explain what’s going on so that developers know how it all works.

Step 5: Write the Reasons Why Your Project Should Be Used

This section should state why you created your project. It should go over the problems it solves. Give reasons why your project should be used. For example:

Simply put, tell developers how your project meets their needs.

Step 6: Write Contributing Guidelines

In some cases, developers might want to help you develop your project. If you’re worried about your code being bloated with things you don’t care about (e.g., too many inline comments), then write contributing guidelines that go over what developers should and shouldn’t do in your project. Typically, this is a separate file in your project’s repository under the name CONTRIBUTING.md and could include sections like the following (these are just a few examples):

• Commit message conventions
• Code doc blocks
• Code of conduct
• Code quality expectations

You only need to link to this file so that developers are aware of it and know where to find it. For example:

Clicking on “here” will bring developers the contributing guidelines file.

Step 7: List the License

It’s common for projects to list the license that applies to them. Some might say it’s required. This license lets developers know what they can and can’t do with your project. Just like the contributing guidelines, this is a separate file in your project’s repository under the name LICENSE. An example of a license is the MIT license. If your project uses the MIT license, then your LICENSE file could look like the following:

Also, since this is a separate file, you only need to link to this file so that developers are aware of it and know where to find it. For example:

Clicking on “MIT” will bring developers to the license file.

Features and technologies

Sometimes developers want to know what features and technologies your project uses and why. You can add a “Features” and “Technology Stack” section as well. These sections could look like this:

The Features section helps make your project stand out. Why would it need to stand out? Well, it’s likely that your project is not the only one of its kind, so consider listing features to help your project shine.

The Technology Stack section tells developers why you’re using the technologies in your project. It’s not necessarily required, but some developers like knowing what technologies your project is using and why. It prevents developers from asking themselves, “I see this dependency defined in this project, but I don’t know how it’s being used. Why is this needed?” 

The above example clearly states the technologies, provides links to each technology in the event developers want to learn more, and explains why the technologies are being used.

Putting It All Together

So now you know about each section and hopefully have the knowledge to write a detailed README. Let’s see what Searchable’s README file looks like when all of the sections are put together.

You might be thinking, “That’s a huge document.” You’re not wrong. You can solve this by adding a Table of Contents section at the top of your README file right after the name/description section. This will allow developers to jump to the sections they’re interested in quickly.

If your project is on GitHub, then you don’t need to worry about adding a Table of Contents section. GitHub adds a Table of Contents icon for every README file at the top left of the README file. For example (the Table of Contents icon is outlined in red):

In Conclusion

Writing a README file takes time, but it’s time well spent. The more time you spend improving your README file and removing ambiguities, the better the development experience will be for developers using your project.

Remember, the README file is the very first documentation page a developer sees and it can welcome developers or it can leave them completely confused and frustrated. This can cause them to turn to another project with better documentation or ask you a bunch of questions. This being said, include a detailed README in your projects and ensure that developers can use your projects with confidence.