How to Structure a Valuable README

A README is the front page headline of a code repository. It is the welcoming committee to new developers and the trailhead for the existing team. It’s also an archive that will exist long past active development.

Here, I’d like to share how I’ve been structuring README files in our repositories recently. I’ve been using this format for internal web apps and microservices. Public libraries, published packages, or exposed CLI tools have their own needs, but some of the sections below might still apply.

A template I’ve been working with will make up the rest of this post. But, first, a few caveats that don’t quite fit into the template.

• Not every one of these sections will apply to every project and, on some projects, your team might have to add specific points of interest. I intend for this template to be a guide, not the end-all-be-all.
• If any section gets too big or feels too complicated for the README, break it off into its own document, but be sure to link to it from the README.
• A lot of these sections will feel hard to write for a fresh repository. If the first iteration only has the header section, that’s fine, but circle back once the repository has established patterns and structure.
• Things like “running locally” or “deployment” might be possible in several ways. I recommend that the README should cover the way that most developers work most of the time. Allow tribal knowledge or other documentation to manage the nitty-gritty and alternative approaches.

Repository Name

Write a brief description of the repository here. The description should include how this repository relates to the broader application ecosystem. I also like to include a small blurb about what the app consists of (an NPM package, node server, React app, etc.) and how it communicates with other systems. It’s also important to include other names that people might refer to this repository as.

You should also include a list of links to important docs and services. For example:

• Generated API docs
• Relevant Confluence pages
• CI/CD Pipelines

Project Organization

In this section, I describe the key pieces of the repository. For instance, how does the repository structure map to the pieces of the application? What file is the front door of the API? What directory holds frontend code? Where can a developer find the database schema? How are tests organized?

First-Time Setup

Dependencies

A list of dependencies that developers will need to install to set up the app for the first time. For example:

• Node, Java, Ruby, etc. versions including preferred version managers
• Docker
• Important tools like the AWS CLI or Terraform

Setup

Steps to configure and build the app for the first time. For example:

1. Install application dependencies with yarn install.
2. Set up the environment by modifying the .env file.

Running Locally

Steps for running the app on a developer’s machine. For example:

1. Start the database using Docker.
2. Run the backend with yarn workspace api start.
3. Run the frontend with yarn workspace client start.
4. Localhost ports for running services.

Running Tests

This section depends largely on what your test suite looks like. For example, how do you run unit tests and integration tests? Do any services need to be running or configured differently when running tests? How do you interpret test results?

Infrastructure Overview

Here, I describe the infrastructure of the application. Do you use AWS, Azure, etc.? How does the data flow? For example, an AWS API Gateway triggers a Lambda that accesses the RDS database instance. Do you configure infrastructure by hand? Or, do you have infrastructure-as-code providers like CloudFormation or Terraform?

Persistent Environments

List of currently deployed application environments and what they are used for:

• Production (URL) – user-facing production environment
• Development (URL) – latest features and fixes
• Sandbox (URL) – unstable environment for experimentation without disrupting development

I also like to create a table in this section that provides links to key infrastructure for each environment like logs, metrics, databases, etc.

Deployment

In this section, briefly discuss the deployment process. Does the CI/CD pipeline auto-deploy to any environments? How frequently do deployments occur for each environment?

Manual Deployment

Steps for if a developer needs to deploy manually. For example:

1. Get sign-off from Project Manager Bob
2. Run the production build script
3. Run the deployment script with specific flags

Debugging/Troubleshooting

This section is for sharing key troubleshooting processes. If things go wrong, where are the best places to start debugging? Offer trailheads in the code, where to find relevant logs, and what other external systems might be culpable or impacted. This is also a good place to describe how a developer with the right credentials might access the database or SSH into other key servers.

Miscellaneous

This section will be different for every project. You might use it to include tips for tricky syntax or places where new developers regularly get confused. You could link to helpful guides or tutorials if the repository uses uncommon tools or frameworks. If this section grows too big, it might be an indication to add a new section of its own or break pieces off into a separate document.