Your README Probably Sucks: It's Time to Make it Better

I can't recall how many times I've stumbled across an interesting project, been excited to start using it, and opened up the README to see… nothing.

Often it's just a simple initial one-liner that GitHub auto-generates for your repository. In better cases there may be some basic (out-of-date) instructions, but mostly I'm still left with more questions than answers:

  • How am I supposed to build your project correctly?
  • What if I need a static library instead of a dynamic library?
  • How should I use your project?
  • How do I satisfy this weird dependency?
  • How can I cross-compile your code?
  • What is this actually doing to make my life better?

A wonderful project with poor documentation is worthless to me. You spent hundreds of hours on your project, so make it easy for users to get started with your project, understand how it will help them, and find answers when they run into problems.

Let's take a look at the information a good README should provide.

First: A Note about "Readiness"

You may be waiting to write your README until your project is finished. This is a mistake.

I recommend a different approach: write as much of your README as you can before you start your project. A great post covering this topic is "README driven development". I highly recommend reading it if you need some motivation to get started.

Writing READMEs can be pretty dull and monotonous, and it's easy to skip your README altogether once you've finished your project. Without a framework in place for you to make updates as you work, you will likely lose track of critical details like important dependencies, setup steps, and solutions to problems that you encountered.

Now that we've gotten that out of the way, let's take a look at the elements of a high-quality README.

Formatting

That's right, I'm putting formatting at the top of the list. If your README is disorganized and poorly formatted, nobody is going to give it the time of day.

Most readers in our present era will be viewing your README in their web browser. Organizing your README into well-organized sections, formatting text so it stands out, and including a table of contents should be a priority.

Familiarize yourself with basic Markdown syntax to properly format your document. Add links to other documents and include images. You can even create a table of contents by using anchor links:

## Table of Contents
1. [About the Project](#about-the-project)
1. [Project Status](#project-status)
1. [Getting Started](#getting-started)

# About the Project

## Project Status

# Getting Started

Length

You want your README to be as short as possible while still explaining basic functionality and setup steps to your user. Long-winded background sections, detailed instructions, or other non-typical documentation should be provided separately and linked to within your README.

We don't want to scare our new users away with a great tome!

By having a well-formatted README, your readers won't immediately run away from a wall of unformatted text.

The Introduction

Your introduction may be the only chance you have to engage with someone who comes across your project. Include a well-crafted introductory paragraph to grab your reader's attention. Provide a high-level summary of what your project accomplishes and how others will benefit from using your project. Emphasize why your project is valuable and how it makes someone's life easier.

I generally include the table of contents in my introduction so readers can jump to a relevant section.

About your project

Include a section which describes your project in more detail than the introduction. Aim to answer these questions:

  • What is your project?
  • What is the intended use of your project?
  • How does it work?
  • Who uses it?
  • How can others benefit from using your project?

Project Status

While the previous section highlighted the goals of your project, we haven't always gotten around to completing those goals. You can include a section describing the current state of your project. This will give your readers a sense of the maturity of your project and areas where they might be able to help you.

Aim to include details regarding:

  • Build status (e.g. status widget from your CI server)
  • Health of the project
  • Information about the current release and how to find it (or link to the RELEASE file)
  • Known issues
  • Items you haven't been able to implement/fix yet
  • Things you're currently working on
  • Whether or not you want to accept contributions

Getting Started on your Project

Most of us only read a project's README in order to figure out how to start using a project. This section should be the bulk of your README contents. Keep in mind that many people start reading documentation only when they encounter a problem. Have you anticipated problems users may have? Are you recording solutions to common problems in an accessible place for new developers?

The easiest way to fill out this section is to help someone who has never used your project get set up, and write down the exact instructions. One you have those instructions ready, ask another person to follow them to see if you missed any critical steps.

You want to cover the following topics:

  • Dependencies that need to be installed for building/using your project,
    • Instructions for installing the dependencies
  • How to configure your project, and information on configuration options
  • How to build your project
  • How to install your project
  • How to run tests
  • How to use your project, or API usage information

Make sure to provide working code and command-line examples for each of these sections. And keep this section up to date!

Contributing

While the previous section covered how to start using your project, this section should provide information for people who are interested in developing on your project.

If you have a CONTRIBUTING file, provide a short blurb mentioning you welcome contributions and link to the file.

If you don't have a CONTRIBUTING file, provide instructions to help other developers get started.

Make sure to cover:

  • Additional setup steps that are specific for development
  • How users can contribute to your project
  • What kinds of assistance you are looking for
  • Information about your development and review process
  • Whether commits should be squashed before merging
  • Information on coding standards
  • Details on whether there are any requirements for contribution (e.g. a Contributor License Agreement)
  • Code of conduct for contributors

If you don't want contributors for your project, explicitly say so!

Other Important Details

There are many other useful details that you should include in your README file.

Release Process

You may also want to include notes on your project's release process:

  • What is your project's release cycle?
  • How can someone find the latest release?
  • What branches are used in the development process? (master, stable, etc.)
  • When are new releases made?

How to get help

Your documentation may not cover all of the problems that a user might have. Provide instructions for users to get more help. Include the best method of contact or a link to a relevant user group.

Further Reading

Your README is just a starting point for your project. Provide links to other references that people can refer to, such as:

  • Library documentation
  • Architecture references
  • FAQ
  • INSTALL file
  • CONTRIBUTING guidelines
  • CODEOWNERS
  • Related blog posts or white papers

Authors

Provide some information on the folks creating and maintaining your project. Include website links, GitHub profile links, and any contact information you want to share.

Acknowledgements

Did you use someone else's code?

Do you want to thank someone explicitly?

Did someone's blog post spark off a wonderful idea or give you a solution to nagging problem?

Provide a shoutout and a link in your README. We are all in this together, and giving credit where it is due is a great way to generate goodwill. And referencing external code also helps users track down the original source for use in their own projects.

License

Provide a summary of the software's license and a link to your detailed LICENSE file.

Also include relevant licenses from any external code that you have included.

Putting it All Together

These are simply guidelines for writing a good README. In my next post, I'll share the README template that I've developed for my own projects.

You can also learn more by looking at other high quality READMEs. Here are a few:[ Also add links to my own projects!]

Remember, your README is the first piece of your project that most people will encounter. If your project is great, your README should be great too.

Further Reading