Readme : condensé des es­sen­tiels et mise en forme

Readme – rien que le nom comporte déjà une in­vi­ta­tion, « Lisez-moi ». Et c’est pré­ci­sé­ment l’objectif de cette dé­no­mi­na­tion. Le fichier readme est le premier fichier qu’un dé­ve­lop­peur doit consulter avant d’entamer un projet. Ainsi, il est capital que les dé­ve­lop­peurs sachent rédiger un fichier readme correct pour y compiler les in­for­ma­tions per­ti­nentes avec concision.

Un fichier readme, souvent readme.txt ou readme.md, contient ha­bi­tuel­le­ment des in­for­ma­tions im­por­tantes à propos du système, du projet ou du logiciel en question. Pour que les uti­li­sa­teurs trouvent im­mé­dia­te­ment ce fichier, on le classe idéa­le­ment au tout premier niveau de l’ar­bo­res­cence.

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

• Pour l’uti­li­sa­teur final, le fichier readme clarifie dif­fé­rents points relatifs à l’ins­tal­la­tion, à la mise à jour ou à l’uti­li­sa­tion d’un logiciel.
• Pour le dé­ve­lop­peur du projet, le fichier readme présente deux avantages. D’une part, un fichier readme rédigé avant le début du dé­ve­lop­pe­ment donne les lignes di­rec­trices 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é­ve­lop­peurs, le fichier readme précise les règles à respecter et donne des in­di­ca­tions pré­cieuses pour pour­suivre le dé­ve­lop­pe­ment et la mise en œuvre d’un système, d’un logiciel ou d’un projet open source.

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

• Une des­crip­tion 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é­ve­lop­pe­ment. Évoquez les mo­di­fi­ca­tions prévues et l’objectif du dé­ve­lop­pe­ment ou signalez clai­re­ment que le dé­ve­lop­pe­ment du projet est terminé.
• Les exigences con­cer­nant l’en­vi­ron­ne­ment de dé­ve­lop­pe­ment en vue de son in­té­gra­tion.
• Une ins­truc­tion pour l’ins­tal­la­tion et l’uti­li­sa­tion.
• Une liste des tech­no­lo­gies utilisées et, le cas échéant, des liens vers d’autres in­for­ma­tions sur ces tech­no­lo­gies.
• Les projets open source que les dé­ve­lop­peurs modifient ou com­plè­tent par eux-mêmes doivent être complétés par un pa­ra­graphe « col­la­bo­ra­tion souhaitée » dans leur fichier readme.md. Comment con­tour­ner un problème ? Comment les dé­ve­lop­peurs doivent-ils appliquer les mo­di­fi­ca­tions ?
• Bugs connus et cor­rec­tions éven­tuelles apportées.
• Section FAQ reprenant toutes les questions posées jusqu’à présent.
• Droits d’auteurs et in­for­ma­tions sur la licence.

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

Vous pouvez créer et en­re­gis­trer un fichier readme dans le format de fichier texte que vous préférez. Les ex­ten­sions vont du readme.txt au readme.doc en passant par le readme.1st. Choi­sis­sez l’extension du fichier readme en fonction du système d’ex­ploi­ta­tion sur lequel sera exécuté le logiciel. Vous vous assurerez ainsi que le programme de trai­te­ment de texte dédié sera capable de lire votre fichier.

Aujourd’hui, les dé­ve­lop­peurs pri­vi­lé­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 uti­li­sa­teurs un aperçu complet du projet.

Nous allons vous montrer comment cons­truire pas à pas un fichier readme.md et quelles pos­si­bi­li­tés de formatage vous offre le format Markdown. Pour permettre une col­la­bo­ra­tion in­ter­na­tio­nale et dépasser la barrière de la langue, rédigez toujours votre fichier readme en anglais.

Exemple de fichier readme au format Markdown :

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

Si la do­cu­men­ta­tion est con­sé­quente, une table des matières sera utile pour en donner un bon aperçu :

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 au­to­ma­ti­que­ment des ID aux titres dans un fichier readme. Ces ID sont dérivées du nom du titre, les espaces sont rem­pla­cées par un trait d’union « - ». Elles sont re­mar­qua­ble­ment utiles en tant qu’ancres de na­vi­ga­tion dans la table des matières. Si le readme.md est conçu pour une autre pla­te­forme qui n’attribue pas au­to­ma­ti­que­ment une ID aux titres, il est possible de créer les ancres de na­vi­ga­tion au format HTML :

La table des matières est suivie des dif­fé­rents blocs de contenu cor­res­pon­dant aux points de la liste :

Les in­for­ma­tions générales sur le projet sont es­sen­tielles pour donner une ex­pli­ca­tion succincte et se faire ra­pi­de­ment une idée du projet. Avec Markdown, vous pouvez aussi compléter la do­cu­men­ta­tion par des gra­phiques, des im­pres­sions é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 pa­ren­thèses (sans espace entre les deux). Précédez l’ensemble d’un point d’ex­cla­ma­tion pour signaler à Markdown qu’il s’agit d’un fichier image.

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

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

Comme les fichiers readme sont bien souvent rédigés dans le cadre du dé­ve­lop­pe­ment 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 uti­li­sa­tion, avec le symbole « ``` » au début et à la fin du code. Vous pouvez aussi utiliser des extraits de code di­rec­te­ment dans le texte.

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

Vous pouvez aussi associer des listes ordonnées et non ordonnées dans un fichier readme.md. Il suffit de pour­suivre la liste ordonnée avec le chiffre cor­res­pon­dant.

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

Le format Markdown prévoit aussi la pos­si­bi­lité de créer des tableaux dans votre readme.md. Utilisez des barres ver­ti­cales « | » et des tirets « - ». Le symbole deux points « : » indique l’alig­ne­ment du texte : à gauche, centré ou à droite.

Retrouvez ci-dessous un ré­ca­pi­tu­la­tif de toutes les balises de mise en forme pré­sen­tées dans cet article et ras­sem­blées en un exemple de pré­sen­ta­tion :