Readme : condensé des essentiels et mise en forme

Readme – rien que le nom comporte déjà une invitation, « Lisez-moi ». Et c’est précisément l’objectif de cette dénomination. Le fichier readme est le premier fichier qu’un développeur doit consulter avant d’entamer un projet. Ainsi, il est capital que les développeurs sachent rédiger un fichier readme correct pour y compiler les informations pertinentes avec concision.

Qu’est-ce qu’un fichier readme (txt/md) et à quoi sert-il ?

Un fichier readme, souvent readme.txt ou readme.md, contient habituellement des informations importantes à propos du système, du projet ou du logiciel en question. Pour que les utilisateurs trouvent immédiatement ce fichier, on le classe idéalement au tout premier niveau de l’arborescence.

Conseil

Le nom du fichier README est souvent écrit en lettres capitales. Les systèmes sensibles à la casse peuvent ainsi mettre ce fichier en tête de liste, avant ceux dont le nom commence par une lettre minuscule.

Le fichier remplit différentes fonctions selon l’usage que l’on veut en faire :

  • Pour l’utilisateur final, le fichier readme clarifie différents points relatifs à l’installation, à la mise à jour ou à l’utilisation d’un logiciel.
  • Pour le développeur du projet, le fichier readme présente deux avantages. D’une part, un fichier readme rédigé avant le début du développement donne les lignes directrices de la mise en place du projet. D’autre part, il se montre très utile pour reprendre un projet qui aurait été mis en pause pendant une longue période.
  • Pour les autres développeurs, le fichier readme précise les règles à respecter et donne des indications précieuses pour poursuivre le développement et la mise en œuvre d’un système, d’un logiciel ou d’un projet open source.

Que doit-on indiquer dans un fichier readme ?

En fonction des objectifs que doit remplir le fichier, on peut y intégrer les contenus suivants :

  • Une description générale du système ou du projet.
  • Le statut du projet, qui est surtout utile lorsqu’il est encore en stade du développement. Évoquez les modifications prévues et l’objectif du développement ou signalez clairement que le développement du projet est terminé.
  • Les exigences concernant l’environnement de développement en vue de son intégration.
  • Une instruction pour l’installation et l’utilisation.
  • Une liste des technologies utilisées et, le cas échéant, des liens vers d’autres informations sur ces technologies.
  • Les projets open source que les développeurs modifient ou complètent par eux-mêmes doivent être complétés par un paragraphe « collaboration souhaitée » dans leur fichier readme.md. Comment contourner un problème ? Comment les développeurs doivent-ils appliquer les modifications ?
  • Bugs connus et corrections éventuelles apportées.
  • Section FAQ reprenant toutes les questions posées jusqu’à présent.
  • Droits d’auteurs et informations sur la licence.

Il est important de rédiger le fichier readme en l’adaptant à son utilisateur final. C’est la meilleure façon de clarifier la plupart des questions qu’il pourrait se poser.

Formats possibles pour les fichiers readme

Vous pouvez créer et enregistrer un fichier readme dans le format de fichier texte que vous préférez. Les extensions vont du readme.txt au readme.doc en passant par le readme.1st. Choisissez l’extension du fichier readme en fonction du système d’exploitation sur lequel sera exécuté le logiciel. Vous vous assurerez ainsi que le programme de traitement de texte dédié sera capable de lire votre fichier.

Aujourd’hui, les développeurs privilégient le plus souvent le format readme.md. Qu'est-ce qu'un .md file ? Cette extension est celle du format Markdown. Le Markdown convertit du texte au format HTML grâce à des balises de formatage simples. Un fichier readme bien formaté et bien structuré offre aux utilisateurs un aperçu complet du projet.

Readme.md : un exemple au format Markdown

Nous allons vous montrer comment construire pas à pas un fichier readme.md et quelles possibilités de formatage vous offre le format Markdown. Pour permettre une collaboration internationale et dépasser la barrière de la langue, rédigez toujours votre fichier readme en anglais.

Exemple de fichier readme au format Markdown :

# Project name
***
Short Description about the project.
Conseil

Avec la balise « *** », insérez une ligne de séparation horizontale.

La première section du fichier readme doit contenir un nom de projet parlant et une courte description du type de projet dont il s’agit. En Markdown, le symbole dièse « # » précède toujours un titre. Le nombre de symboles correspond au niveau de titre :

# Headline H1
## Headline H2
### Headline H3
#### Headline H4
##### Headline H5
###### Headline H6

Si la documentation est conséquente, une table des matières sera utile pour en donner un bon aperçu :

## Table of Contents
1. [General Info](#general-info)
2. [Technologies](#technologies)
3. [Installation](#installation)
4. [Collaboration](#collaboration)
5. [FAQs](#faqs)

La table des matières du readme.md se structure grâce à une liste ordonnée. Il vous suffit d’indiquer le chiffre au début d’une ligne pour créer la liste.

GitHub ajoute automatiquement des ID aux titres dans un fichier readme. Ces ID sont dérivées du nom du titre, les espaces sont remplacées par un trait d’union « - ». Elles sont remarquablement utiles en tant qu’ancres de navigation dans la table des matières. Si le readme.md est conçu pour une autre plateforme qui n’attribue pas automatiquement une ID aux titres, il est possible de créer les ancres de navigation au format HTML :

## Table of Contents
<a name="general-info"></a>
### General Info

La table des matières est suivie des différents blocs de contenu correspondant aux points de la liste :

## General Info
***
Write down the general informations of your project. It is worth to always put a project status in the Readme file. This is where you can add it.
### Screenshot
![Image text](/path/to/the/screenshot.png)

Les informations générales sur le projet sont essentielles pour donner une explication succincte et se faire rapidement une idée du projet. Avec Markdown, vous pouvez aussi compléter la documentation par des graphiques, des impressions écran et d’autres images. Pour ce faire, il vous suffit d’écrire un mot entre crochets, suivi de l’URL de l’image entre parenthèses (sans espace entre les deux). Précédez l’ensemble d’un point d’exclamation pour signaler à Markdown qu’il s’agit d’un fichier image.

## Technologies
***
A list of technologies used within the project:
* [Technologie name](https://example.com): Version 12.3
* [Technologie name](https://example.com): Version 2.34
* [Library name](https://example.com): Version 1234

Avec le format Markdown, créez les puces d’une liste non ordonnée avec un astérisque « * » au début de la ligne.

Markdown permet d’insérer des liens à n’importe quel endroit du fichier readme.md. La construction est très similaire à celle employée pour insérer une image, sans le point d’exclamation en début de ligne. Écrivez le mot servant de lien entre crochets, puis le chemin d’accès à la page Internet entre parenthèses (toujours sans espace entre les deux).

Note

Les fichiers doivent toujours être dans le même dépôt. Vous pouvez aussi utiliser d’autres fichiers publics, en prenant cependant le risque que le propriétaire de ces fichiers les supprime un jour et les fasse disparaître de votre readme.md.

## Installation
***
A little intro about the installation.
```
$ git clone https://example.com
$ cd ../path/to/the/file
$ npm install
$ npm start
```
Side information: To use the application in a special environment use ```lorem ipsum``` to start

Comme les fichiers readme sont bien souvent rédigés dans le cadre du développement d’un logiciel, il s’avère pertinent de copier des exemples du texte source dans le document. Markdown propose une option de formatage pour cette utilisation, avec le symbole « ``` » au début et à la fin du code. Vous pouvez aussi utiliser des extraits de code directement dans le texte.

## Collaboration
***
Give instructions on how to collaborate with your project.
> Maybe you want to write a quote in this part.
> It should go over several rows?
> This is how you do it.

Le symbole « > » au début d’une ligne transforme le texte en citation.

## FAQs
***
A list of frequently asked questions
1. **This is a question in bold**
Answer of the first question with _italic words_.
2. __Second question in bold__ 
To answer this question we use an unordered list:
* First point
* Second Point
* Third point
3. **Third question in bold**
Answer of the third question with *italic words*.
4. **Fourth question in bold**
| Headline 1 in the tablehead | Headline 2 in the tablehead | Headline 3 in the tablehead |
|:--------------|:-------------:|--------------:|
| text-align left | text-align center | text-align right |

Vous pouvez aussi associer des listes ordonnées et non ordonnées dans un fichier readme.md. Il suffit de poursuivre la liste ordonnée avec le chiffre correspondant.

Pour l’exemple, nous avons inséré des phrases en italique et en gras. Mettez une phrase en italique en ajoutant un astérisque « * » ou un tiret bas « _ » au début et à la fin de votre phrase. Pour mettre le texte en gras, ajoutez deux astérisques ou deux tirets bas.

Le format Markdown prévoit aussi la possibilité de créer des tableaux dans votre readme.md. Utilisez des barres verticales « | » et des tirets « - ». Le symbole deux points « : » indique l’alignement du texte : à gauche, centré ou à droite.

Exemple de présentation d’un fichier readme

Retrouvez ci-dessous un récapitulatif de toutes les balises de mise en forme présentées dans cet article et rassemblées en un exemple de présentation :

## Table of Contents
1. [General Info](#general-info)
2. [Technologies](#technologies)
3. [Installation](#installation)
4. [Collaboration](#collaboration)
5. [FAQs](#faqs)
### General Info
***
Write down the general informations of your project. It is worth to always put a project status in the Readme file. This is where you can add it. 
### Screenshot
![Image text](https://www.united-internet.de/fileadmin/user_upload/Brands/Downloads/Logo_IONOS_by.jpg)
## Technologies
***
A list of technologies used within the project:
* [Technologie name](https://example.com): Version 12.3 
* [Technologie name](https://example.com): Version 2.34
* [Library name](https://example.com): Version 1234
## Installation
***
A little intro about the installation. 
```
$ git clone https://example.com
$ cd ../path/to/the/file
$ npm install
$ npm start
```
Side information: To use the application in a special environment use ```lorem ipsum``` to start
## Collaboration
***
Give instructions on how to collaborate with your project.
> Maybe you want to write a quote in this part. 
> It should go over several rows?
> This is how you do it.
## FAQs
***
A list of frequently asked questions
1. **This is a question in bold**
Answer of the first question with _italic words_. 
2. __Second question in bold__ 
To answer this question we use an unordered list:
* First point
* Second Point
* Third point
3. **Third question in bold**
Answer of the third question with *italic words*.
4. **Fourth question in bold**
| Headline 1 in the tablehead | Headline 2 in the tablehead | Headline 3 in the tablehead |
|:--------------|:-------------:|--------------:|
| text-align left | text-align center | text-align right |
Conseil

Avec l’éditeur WYSIWYG de Dillinger, créez rapidement et facilement un fichier readme.md en ligne.