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 :
-
- Singers, Matias, « Awesome README », 26 juin 2018
- Thompson, Caleb, « How To Write A Great README », 12 juin 2015
- Guo, Danny, « Make a README », 8 juin 2018
