A README is the best place to start documenting a project. A README is normally a single-page document describing your computer project’s key aspects. This document can be read in a few minutes maximum. It is the open door for a newcomer who wants an overview of the fundamental aspects of the project.

Having a README for a computer project is a common enough thing for the code repositories. Still, the template defining what should contain this README is not standard and often depends on the sensibility of the software documentalist. Avoiding gaps in content and format allows you to align the shared knowledge of your projects in the best common possible way.

The rules for writing a README file will be described with a generic template and a pragmatic methodology agnostic to the tech stack and the project type you use.

First, let’s begin defining the type of project that you can have.

A project is a code repository; it can be composed of either one module (simple project) or several modules (complex project). This project is in an ecosystem composed of dependencies between modules of the same project or other projects. A module can be :

• An application: It is deployed at runtime with an executable. No other module depends on it except optionally at runtime.
• A library: It’s used by other modules that depend on it for their execution and/or build.

For example, a type of project can be a code library in (Python, Scala, or Java …), an SDK, a web app with a UI and/or an API, a machine learning model, a data processor, a set of scripts, an OPS configuration module or a scheduled job …

All projects have not necessarily needed a README respected rigorous template; it can use a degraded version in function efforts that you want to provide. Only mature projects where you want a high level of quality need it, that is to say, for a project used by the community in an intensive or critical way.

Practical guidelines

Here are explained the practical guidelines that a README should respect.

For a simple project:

• The README should be a simple text file called README..
• It should be written in coherent syntax (like Markdown or reStructuredText).
• There should be a README at the root of the project.
• According to the README variant you choose (see sections below), you need to adhere to the variant structure.

For a complex project:

• The README at the root must have links to the ones of each submodule, with a sentence to describe the role of each module
• It should have a README for each module
• The README of each module should respect the guidelines of a simple project

Template

Here are the sections that README should contain.

Each section can contain direct or indirect information with links and should contain a title section with format H1 (i.e., ‘#’ with markdown). A section can be optional and required in function of the type of modules.

• [Project Title]* [*: required]
  • High-level description (with a demo link if applicable)
  • It should indicate if it is a library or an application - It should indicate who is the owner of this project
• Quick start* [*: required]
  • How to set up the development environment, get the repository, install tech stack, …
  • Link to a demo
  • How to run the project
  • How to run the tests
• Usage [optional only if relevant and helpful]
  • How to use the project (ex. API description)
  • Links to help resources
  • How to contribute to the project (coding style, code of conduct, …)
• Main structure* [*: required]
  • Link(s) to other “sub-README(s)” (only if the module has submodules)
  • Links to dependencies
  • Describe the file architecture of the repository
• Architecture [optional only if relevant and helpful]
  • Explanation of the design with a diagram and a description …
• Deployment** [**: required only for a deployed application]
  • Link to the deployment configuration
  • Link to this history of the deployment with the changelog and the releases
  • Link to the deployed application
• Monitoring** [**: required only for a deployed application]
  • Links to monitoring dashboards, …
• References [required]
  • Links to the documentation about specifications, improvements, or maintenance…
  • Other useful links
• License
  • Link to the license and copyright with the general conditions

👀 Read more

Read the rest of the article …