How to Write a README

In the root directory of a code project, you will often find a README.md. What is a README? It is the project’s self-introduction — much like a resume, its purpose is to sell itself: to get a company to hire you, or to get others to adopt your project.

In this post, I will try to introduce how to write a good README.

Writing a README can follow the 5W1H framework (what, why, when, how, where, who). The most important dimensions are What, Why, How, and Who.

What

What covers mainly two aspects:

• What is it?
• What can it do? (What features does it provide?)

For example, in the README of Kubernetes:

Kubernetes, also known as K8s, is an open source system for managing containerized applications across multiple hosts. It provides basic mechanisms for deployment, maintenance, and scaling of applications.

From this passage, we learn the following:

• Kubernetes, also known as K8s, is an open source system for managing containerized applications across multiple hosts. (What it is)
• It provides basic mechanisms for deployment, maintenance, and scaling of applications. (What it can do)

Beyond what it is and what it can do, you may also include the project’s origin, license, and so on.

Why

Why focuses on explaining the motivation:

• Why was it built?
• What problem does it solve?
• What benefits does it bring?

For example, in the README of Hashicorp Vault:

A modern system requires access to a multitude of secrets: database credentials, API keys for external services, credentials for service-oriented architecture communication, etc. Understanding who is accessing what secrets is already very difficult and platform-specific. Adding on key rolling, secure storage, and detailed audit logs is almost impossible without a custom solution. This is where Vault steps in.

The first sentence provides context, the second describes the difficulties faced in that context, and the final sentence tells the reader that Vault is the tool designed to solve these problems.

As for the benefits, this section often overlaps with the features described under What.

Who

Who covers the following:

• Who maintains the project?
• Who are the contributors?
• How to communicate? For example, a Slack channel.

Regarding who maintains the project: in open-source projects, it is generally assumed to be the community or the repo owner. However, in internal projects, as team members come and go, it is quite necessary to note which person or team is currently responsible for maintaining the project.

As for contributors: in many open-source projects, you will see the avatars of code contributors displayed in the README. This encourages more people to contribute.

For example, the Contribution section in Vue does exactly this.

Communication channels overlap somewhat with content described below. Providing one or more platforms for announcements, discussion, and feedback is always helpful.

How

This section focuses on two types of people: users and developers.

For users, we need to provide the following information:

• Prerequisites. Which dependencies need to be installed? What credentials are required? For example, if I write a docker-compose file for running Jenkins locally, the prerequisites would be: Docker and docker-compose must already be installed locally.
• How to install? A personal recommendation: provide a script for one-command installation to lower the barrier to entry.
• How to use it?
• How to uninstall? This is missing from the vast majority of projects. Sometimes a user just wants to try something out, but after installation finds there is no way to remove it — which is genuinely frustrating.
• How to provide feedback? If a user encounters a bug, where should they report it? Typically, users can file an issue, so this does not always need to be written explicitly. If the process is different from the standard, it should be documented.

This content is usually grouped under headings like Documentation or Getting Started.

For example, in Hashicorp Vault, the section “Documentation, Getting Started, and Certification Exams” tells users how to get started.

Similarly, in Vue, the Documentation section links to examples and docs, and the Issues section tells users how to create an issue when they encounter a problem.

For developers — people who are interested in your project, want to add features, or have found a bug and want to help fix it — you should provide a Contributing Guide that includes:

• Tech stack. Consider using badges to highlight key dependencies. See https://shields.io/ for badge references.
• Code of Conduct
• CI/CD status. Badges are recommended here as well.
• How to run tests?
• How to run code style checks?
• How to build?
• How to submit code? If multiple branches are involved, explain the purpose of each branch.

Not every item above is always necessary, and the list is not exhaustive. This content typically appears under headings such as Development or Contributing.

For example, in Hashicorp Vault, there is a subsection called “Developing Vault” that guides developers on how to contribute.

In Vue, rather than putting contributing instructions directly under a “Contributing” heading, the content is moved to a separate page — which is an excellent practice. When writing a README, if a section becomes too long, it should be moved to a separate file. Keeping the README complete, concise, and well-organized is important. Do not try to increase the reading burden on your audience (whether users or developers).