Fichier souvent négligé, le README.md, à la base d’un repository GitHub, peut se révéler pourtant très utile, au projet comme à son ou ses développeurs.
Que cela soit pour présenter le projet, en donner les détails techniques, se créer un véritable portfolio ou gagner en visibilité, le README.md, s’il est bien fait, présente un véritable intérêt.
Vous voulez connaître tous les secrets de ce fichier oublié ? Maîtriser le markdown, ce langage utilisé pour l’écrire ? Savoir comment créer le README idéal ? Suivez le guide !
Qu’est-ce qu’un fichier README.md ?
Tout d’abord, commençons par définir ce qu’est un README pour bien comprendre comment il fonctionne.
Lorsque l’on ouvre un projet sur GitHub, on peut voir en dessous de la liste des fichiers du projet un bloc avec du texte, des images, des liens, etc. : c’est le contenu du fichier README.md.
Plus concrètement, il contient généralement la documentation du projet : installation, utilisation, roadmap, licence, etc.
Son nom vient de read me, et son extension, .md, signifie markdown, un langage de balisage pour le formatage de texte.
Pour résumer, le README est donc un fichier écrit dans un certain langage et interprété par GitHub pour en afficher un contenu formaté. En cela, il est comparable au HTML.
Pourquoi prendre du temps pour son README.md ?
Nous en avons rapidement parlé, il y a plusieurs raisons qui devraient pousser un développeur (ou une équipe) à prendre soin du fichier README.
Déjà, c’est le premier élément que l’on voit lorsqu’on arrive sur un repository GitHub. S’il est mal écrit, mal organisé, il donnera une mauvaise première impression aux visiteurs. Peut-être même qu’ils refuseront d’utiliser ce projet (si c’est un plugin, par exemple), par manque de clarté dans sa définition.
Aussi, son utilisation première est de servir de documentation. Si vous voulez que votre projet GitHub, que cela soit un framework ou une extension, soit téléchargé et utilisé, il faut qu’il ait une documentation explicite et limpide.
Un README.md bien écrit peut également faire gagner un développeur en visibilité. Si, par exemple, un développeur freelance est en recherche de mission et qu’un recruteur ou CTO parcourt ses projets GitHub (s’il en a), voir des repositories bien structurés et clairs, cela peut faire la différence.
D’ailleurs, et c’est assez peu connu, un README.md peut être utilisé pour se créer un portfolio. Depuis 2020, GitHub permet en effet d’héberger le contenu de son README.md, pour se présenter soi et ses projets. Si cela vous intéresse, nous avons écrit un article complet expliquant comment se créer un portfolio via un README.md !
Comment faire un README sur GitHub ?
Maintenant que nous avons vu l’intérêt du README, voyons comment faire pour créer le README parfait pour votre projet !
La syntaxe du markdown
Mais avant toute chose, faisons le point sur le markdown, le langage de balisage utilisé pour écrire le README.md.
Si les règles du markdown ne sont pas très difficiles à comprendre, il n’est pas simple de connaître par coeur toutes les possibilités qu’il offre, et elles sont nombreuses :
- la mise en forme de texte (heading, italique, gras, paragraphes, etc.) ;
- l’ajout de citations, citations contenant du code ;
- de liens, internes ou externes ;
- d’images ;
- de listes de tâches ;
- l’utilisation d’emojis.
Et la liste n’est pas complète !
Pour bien comprendre cette syntaxe particulière, le mieux est de voir quelques exemples.
Pour le heading, on utilisera le caractère ‘#’. On pourrait le comparer au Hn du HTML :
# sera équivalent au H1
## sera équivalent au H2
### sera équivalent au H3
#### sera équivalent au H4
##### sera équivalent au H5
###### sera équivalent au H6Ce code par exemple, une fois hébergé sur GitHub, rendra :
Concernant la mise en forme du texte, voici quelques unes des règles basiques :
Ainsi, le code markdown suivant :
**Je suis un texte en gras**
*Je suis un texte en italique*
**Je suis un texte en gras _avec un passage en italique_**
> Je suis une citation
`je suis du code`Donnera donc en sortie :
Enfin, une liste de tâches sera écrite de la façon suivante :
- [x] #739
- [ ] <https://github.com/octo-org/octo-repo/issues/740>
- [ ] Add delight to the experience when all tasks are complete :tada:Ce qui donnera, une fois interprétée par GitHub :
Comme nous le voyons, on peut même aller encore plus loin avec la liste des tâches, en référençant directement des issues Git.
Pour tout savoir sur la syntaxe du markdown, rendez-vous sur la documentation créée par GitHub.
La checklist du README idéal
Le contenu d’un README dépendant du type de projet hébergé, des langages utilisés, etc. il est impossible de définir une seule trame applicable partout. On peut néanmoins lister quelques règles qui, si elles ne doivent pas forcément toutes êtres suivies, aideront à créer un README propre et agréable à lire.
Par exemple, si on veut créer de la documentation pour un plugin hébergé sur GitHub, on pourrait imaginer les éléments suivants :
- un titre, le nom du projet ;
- une description de ce que fait le plugin, sans trop entrer dans la technique ;
- Les pré-requis à l’utilisation du plugin (version de node si besoin, dépendances, etc.)
- le guide d’installation (les commandes à exécuter pour l’installation, les éventuels problèmes qui peuvent intervenir, etc.) ;
- le guide d’utilisation : les méthodes, leurs options, ce qu’elles retournent, etc.
- une roadmap, pour présenter ce que vous avez prévu pour le futur du plugin, avec d’éventuelles dates comme jalons ;
- la licence d’utilisation, si vous voulez notamment limiter l’utilisation de votre plugin ;
- les divers contributeurs, s’il y en a, ainsi qu’un moyen de les ou de vous contacter directement.
Également, il est recommandé d’inclure les éléments suivants dans votre README GitHub :
- des images (y compris gif), si cela a du sens ;
- divers liens, vers des vidéos de présentations, des exemples d’implémentation ;
- des retours d’expériences, s’il y en a.
Si tous les éléments de ces deux listes ne sont pas obligatoires, et encore moins dans cet ordre en particulier, cela peut au moins vous donner une idée de ce qui devrait être inclus dans un README.
Utiliser des générateurs de doc README
Comme nous l’avons dit, il n’est pas forcément facile de retenir toutes les règles du markdown ; il existe heureusement des outils pour nous aider à créer ce fichier GitHub.
Il y a par exemple le site Makeareadme, qui permet, via un éditeur et une double fenêtre, de voir en temps réel le résultat du code écrit en markdown.
Nous pouvons aussi citer le projet readme-md-generator, qui va lui encore plus loin. Il s’agit d’un plugin qui, une fois installé, va venir lire l’environnement de votre projet pour générer un template README adapté à votre repository. En clair, une fois la commande de ce plugin lancée, le terminal vous posera des questions sur votre projet (en se basant sur l’environnement local) et, en fonction de vos réponses, génèrera un README.md. Le fichier généré restera simple, relativement générique, mais sera déjà une bonne base pour un fichier markdown de qualité.
Conclusion
Nous l’avons vu, le fichier README.md de GitHub est important, bien qu’il soit souvent sous-estimé. Via des outils spécifiques et en connaissant les règles de base, il est possible de générer rapidement un fichier bien formaté, qui sera utile non seulement aux visiteurs d’une page GitHub, mais aussi à d’éventuels recruteurs.
