2 Associés est une agence web de Montréal spécialisée en développement web et mobile, stratégie de contenu SEO, SEM et les technologies langagières.

Vous voulez discuter?

README, sa structure et son contenu

README, sa structure et son contenu

Le fichier README est une partie importante de tout projet, « Open Source » ou non. Le README est un fichier texte, souvent en « Markdown », qui nous introduit au projet. Même s’il est très utile et principalement adressé aux développeurs, le README peut contenir des informations moins techniques servant à mieux comprendre le sujet du projet.

D’où provient le terme « README »?

La nomenclature semble remonter aux années 70, avec le PDP-10, et possiblement bien avant, soit à l’époque des cartes perforées avec une note « READ ME! » manuscrite sur le dessus de la pile afin d’expliquer la procédure à suivre.

Le modèle « README » tout en majuscule est consistant à travers l’histoire. En plus d’être distinctif des autres fichiers adjacents, les systèmes UNIX trieraient les majuscules avant les minuscules, plaçant « README » avant tout le reste du contenu d’un répertoire.

Dans tous les cas, l’intention est claire : « Ceci est une information importante à lire avant de continuer. »

Structure minimale

Les éléments clés d’un README sont :

Informations générales
Inclus le titre, sous-titre et/ou slogan optionnel, ainsi qu’un paragraphe résumant adéquatement le projet.
Démarrage
Ces instructions vous permettrons de prendre connaissance des pré-requis et d’installer le projet afin de pouvoir développer et tester localement.
Auteurs
Liste des auteurs, avec leur titre et l’entreprise pour laquelle ils ou elles travaillent. Les contributeurs peuvent être énumérés à la suite ou dans un document séparé, exemple CONTRIBUTING.md.
License
Traite de la licence d’utilisation permise, ou non, principalement dans les projets publics.

Autres éléments

Outre les éléments clés, on peut également inclure les informations suivantes :

Guide et standardisation
Cette section informe sur les normes et conventions de développement adopté par l’équipe pour assurer une cohérence dans le code source.
API
Si votre application consomme une ou plusieurs API, cette partie inclus toutes les informations pertinentes les concernant.
Exécution et écriture des tests
Contient les informations nécessaire pour rouler les tests automatisés et comment en écrire selon les styles : « e2e, unit, acceptance, etc. »
Compilation
Inclus les commandes pour compiler le code avant le déploiement.
Déploiement
Tout ce qu’il faut savoir sur la ou les méthodes de déploiement selon les environnements.
Fonctionnalités
Simple liste des principales fonctionnalités. Pratique dans les projets « Open Source ».
Technologies
Si votre projet inclus d’autre projets/modules, énumérer ces derniers avec les liens vers leurs documentations respectives.
Comment contribuer
Surtout présent dans les projets « Open Source », cette section informe sur la procédure à suivre pour contribuer au code source. Si celle-ci comporte plusieurs étapes, un fichier type CONTRIBUTING.md est la norme.
Versionnement
Un peu à la manière de Guide et standardisation, cette section traite de la méthodologie applicable au code source, par exemple l’utilisation du Semantic Versioning ou GitFlow.
Crédits
Énumère les salutations à d’autres projets ayant servi de près ou de loin au projet en cours, les sources d’inspiration, etc.

Le README doit avant tout renseigner sur le projet

Que vous adoptiez la version minimale ou plus élaborée, la structure du README doit avant tout renseigner sur le projet, afin d’aider rapidement les développeurs, ou autres ressources, à comprendre en quoi le projet consiste.

Un fichier README est comme le visage de votre projet. C’est le premier fichier qu’une personne devrait lire, et il devrait être écrit très brièvement et donner une introduction très basique au projet.

Si vous avez besoin d’aide pour mettre en place une structure de README adéquate pour vos projets, n’hésitez pas à communiquer avec nous.

Ressources externes :

Commentez cet article

Votre adresse de courriel ne sera pas publiée. Les champs obligatoires sont indiqués avec *

Articles reliés