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 essentially worthless. I’m sorry to say it, really, because I’m sure that you spent hundreds or thousands of hours developing your awesome project. But without documentation, how can we begin to use it?
Your awesome project needs an equally awesome README. Let’s take a look at the information it should provide.
Table of Contents:
- First: A Note about “Readiness”
- Formatting
- Length
- The Introduction
- About Your Project
- Getting Started on Your Project
- Contributing
- Other Important Details
- Putting it All Together
- Further Reading
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 StartedLength
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 the next post, I’ll share the README template that I’ve developed for my own projects. You can also find our README template (along with other open source templates) in our embeddedartistry/templates GitHub repository.
You can also learn more by looking at other high quality READMEs. Here are a few:
- Embedded Artistry’s README Template
- PurpleBooth’s README Template
- MIDAS README
- Pageres README
- A Curated List of Awesome READMEs
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
- Embedded Artistry’s README Template
- embeddedartistry/templates repository – containing our README template files along with other documentation templates
- GitHub Markup README
- GitHub: Basic Writing and Formatting Syntax
- README Checklist
- Making READMEs Readable
- How to Write a Great README
- README Driven Development
- A Beginner’s Guide to Writing a Kickass README
- A Beginners Guide to Creating a README
- GitHub: About READMEs
- Top 10 Reasons I Won’t Use Your Open Source Project
I’m struggling with restructuring documentation for an existing repository and this gave me valuable inspiration. Thank you!