How to write the README for your repositories
README is important — no matter if your software is open-source or purely internal. It will form the first impression of your code. The main goals of your README should be to convey the necessary information about what your code does and instructions for other developers to set up and contribute changes as soon as possible.
Here is a checklist for the perfect README.
Title
Your repository needs a name. People will refer your project by that name. Good projects have memorable names. Even better when they connect to the primary functionality of the project. While it is not a hard requirement, make sure the name is generic enough to convey its intent.
Linkerd
It is a good name. The name states that it is a daemon (side-car container); inherited from UNIX convention for naming background daemons; which is used to link other containers.
Description
Next to follow is a two-line description of what your code does. Include links to external documentation, if any, detailing design decisions and usage documentation. This should be succulent enough to describe your project in entirety.
Vault is a tool for securely accessing secrets. A secret is anything that you want to tightly control access to, such as API keys, passwords, certificates, and more. Vault provides a unified interface to any secret while providing tight access control and recording a detailed audit log.
Taken from the description of Vault. It states the intent and purpose of the project as a tool for securely accessing secrets. That’s precisely what Vault does.
Also, if you find your description becoming too long, perhaps your project is doing too many things.
Dependencies
List all important runtimes and libraries your project depends on, with proper version constraints. Such as:
This project requires Python 3.6+
If your project is a micro-service, List down all upstream services the code depends on as well. This helps to quickly find out the impact of a potential change, the possible cases that need to be tested after a change is finalized and quick failure resolution when something breaks. Something like,
This project requires, order service, auth service and wallet service (degraded if unavailable)
The above example says that the service requires order service and auth service to work. It also says that the service depends on wallet service but can survive an outage of the same by presenting some degradation in functionality.
Impact on downtime
This applies to services. Describe, in terms of business metrics and user experience, what would happen if the service degrades or fails. This gives other engineers an insight about what to expect during a planned downtime or during failure planning. This will also help you to plan your reliability efforts. Here’s one example:
The failure of this service will cause a delay in order processing, but no loss to business and no visible impact on customers.
Usage
For libraries, users appreciate a short usage section with few examples highlighting the most important parts of the API interface. Include instructions to import the library using the language native package manager if applicable.
For services, describe any configuration that your code uses and provide links to API documentation.
For a tool intended to be consumed by a user, provide documentation about the capabilities of the tool and any settings they need to tweak.
For a reference, check out the usage section of tqdm.
Build
This section is for other developers who want to modify/contribute to your codebase. Detail out the requirements, SDK versions, databases and any other auxiliary software required to compile and run a development copy of this code. Ideally, you should include all steps required to setup the development environment, provision resources and build the project.
Additional notes
This section is for mentioning additional comments related to a project. Here are a few suggestions:
- You can attach links to similar projects and related projects which work in tandem with your project.
- You may also include links to dashboards to your metrics monitoring or log aggregation software.
- You can include FAQs or other information such as known limitations or incompatibilities.
For OSS: License
License is very important for OSS. It provides others with the freedom to use your code in terms set by you to protect your own interests. Your README should include at least a copyright line along with a reference to a license. If you are using your own license, provide a link to the page where users can read the license terms.
A good README provides clear and unambiguous information to get started with a project. I hope this checklist helps you to write good READMEs.