·1 min de lecture

Why having a Readme on your internal project is essential

Auteur(s) de l'article

README.md are those files that's typically at the root of a Git repositories — especially on Open Source project. 
It is unfortunate that corporation and agencies often neglect or ignore the importance of a well-written README.md file.
Despite the long-standing recognition of its value in open source communities, many company fail to provide a proper Readme file for their internal projects.
As a result, it can be challenging for 3rd parties to contribute, audit or interact with the project.
Tweet from @iamdeveloper
When you make your code available to others, the main difficulty is that it might not be immediately clear how to use it. This is where the README.md file can be of great assistance.
The Readme serves as a guide that explains the purpose of your project, provides instructions for installation, offers guidance on how to use it, and includes information on how to contribute to the project.
An example README for a Drupal Open Source project. Imperfect, but attempting to give guidance.

What should I write in my Readme ?

For open-source projects, the README.md file typically includes information about the purpose of the code and instructions on how to use it, as well as how to build it.
Open-source project and internal projects have different audiences, therefore your README must reflect those differences.
From my opinion, The README.md of any corporate project should primarily focus on assisting new developers bootstraping the code on their workstations. Additionally, the Readme should serve as a source of truth for used framework and technologies. 
Finaly, the README.md must contains guidance about common troubleshootings, deployment process, automated-testing and CI/CD pipelines.
You can’t have a bad Readme, If there is no Readme.
By ensuring that the Readme file is comprehensive, developers can better collaborate and maintain the codebase.

When should I start a Readme ?

During many years, I used to procrastinate and leave documentation until the very end of the project.
However, I soon realized I felt overwhelmed going back to the start of what I had built in order to document it properly. Worst, my attempts at documentation were mediocre and incomplete. Mostly because I had lost touch with the project’s subject matter over time.
As part of my ongoing effort to improve, I’ve made creating good documentation a priority. Although it may seem tedious, I’ve discovered that starting every new development effort with a simple README.md has changed my perspective on documentation.
The characteristic of documentation is to be incomplete, imperfect and doomed to disappear. And yet, documentation, with all these flaws, is still necessary in a project.

How can I ensure my Readme is well-written ?

Although I don’t wish for a high turnover in your company, every time a new developer joins the project, you should take that opportunity to challenge your README.
During the onboarding process, ask the person to use the project Readme and once done, discuss pain points together and adapte the README.md.
Keep in mind your documentation will need to be maintained, will have many flaws and some day will be replaced. Still you must create something that will help both your future self and newcomers for the sake of your client and their projects.


Xzibit meming about README
Here a skeleton of README.md that we use at Antistatique. I hopes it may helps you structure your internal project.
#  🎮👾 My Awesome Project

Swiss Games Garden API project is based on 💦 [Drupal](https://drupal.org/), 🕸 [Json:API](https://jsonapi.org/) and 🥃 [Gin](https://github.com/EasyCorp/EasyAdminBundle) as Admin UI.

We built it around 🔍 [Elasticsearch](https://www.elastic.co/) to expose Search Engine capabilities.

It uses 🐳 [Docker](http://docker.com/) for running.

We use 📝 [Swagger](https://swagger.io/) for documentation and ✅ [PHPUnit](https://phpunit.de/)/[Behat](https://docs.behat.org) for testing.

We deploy with 🚀 [Capistrano](https://github.com/capistrano/capistrano) and mange our dependencies with 🎶 [Composer](https://getcomposer.org/) & 🏜 [Phive](https://phar.io/).

## 🔧 Prerequisites

First of all, you need to have the following tools installed globally on your environment:

* docker
* composer
* drush
* phive

don't forget to add bins to your path such:

* php

## 🐳 Docker Install

### Project setup

Explain how to setup the project in order to have an up-and-running instance locally.

### Project bootstrap

Explain how to bootstrap the projec with fake data.

### Project configuration

Once the project up and running via Docker, you may need to setup some configurations in the `.env`.

## 🚔 Static Analyzers

If you have some Static Analyzer, list them.

## 🚀 Deploy

## 🔍 Search Engine

Your project use a specific tool such as a Search Engine (Solr, Elasticsearch, ...).
Then explain this tool and it's integration.

## 📋 Documentations

Explain other extra documentation you may use (Swagger, Insomnia, ...)

## 🚑 Troubleshootings

Most of the project have "common" issue that most newcommers may face (Elasticsearch server can't be reached, Storage full, ...).

Having a commong troubleshooting section will help you reduce friction.

## 🏆 Tests

Explain how tests should be launched.

1. PHPUnit tests must be run on the `test` container with the following cmd:

docker-compose exec test phpunit

## 💻 Commands

Does your project expose some CLI Command ?

## 🕙 Crons

Crons are often only configured on staging/production server. Don't forget to document them.

## Every 5 minutes
*/5 * * * * root /var/www/docker/cron.sh 2>&1

## 📢 RSS

Does your project expose any RSS Feed ? List them here then.

## 📈 Monitoring

Explain here the used solution for Monitoring the project (New Relic, Sentry, ...).

## Authors & Maintainers

Here will be listed people contributing to the project.

👨‍💻 **Kevin Wenger**

* Twitter: [@wengerk](https://twitter.com/wengerk)
* Github: [@wengerk](https://github.com/wengerk)

## 🤝 Contributing

Contributions, issues and feature requests are welcome!

Feel free to check [issues page](https://github.com/acme/my-project/issues).


Matt Ogtong (Nov, 2020) The Importance of README.md Files.
Ankit Rastogi (Aug, 2018) Project Documentation: Does a project really need it?
Mike Ericson (Feb, 2020) Readme Files for Internal Projects.
Charles L Flatt (Mar, 2021) How (and why) to maintain a README.md file for internal projects: Onboarding and Continuous Integration.
GitHub (2022) The ReadME Podcast
Eddie Jaoude (2021) The README is the most important file in your GitHub projects.
Haris Hashmi (Dec, 2021) Don’t ignore your Readme Files.
Haris Hashmi (Dec, 2021) Don’t ignore your Readme Files.
Rosie Wilt (May, 2020) Your Project Isn’t Finished Without a README.
Python Community README — Gateway to Your Code
Midjourney (2022)


Mise à jour le: 20 February 2023