Vous pensez sans doute que personne ne lit les fichiers README.md et vous négligez donc sans doute ce que vous pensez être une corvée ?
Quelle que soit la teneur ou l’ambition de votre projet, vous devez être fier des heures que vous avez consacrées à l’écriture de votre code ; vous ne savez pas qui s’y intéressera dans les semaines, les mois ou même les années à venir.
Vous pourriez vouloir montrer votre projet à votre ami. Ou votre futur employeur peut vouloir vérifier vos projets Github existants.
La rédaction d’un bon fichier README.md témoigne que votre projet vous tient à cœur et peut inciter d’autres développeurs à s’y intéresser, voire à y contribuer. Mais alors, comment rédiger un bon fichier README.md ? C’est ce que nous allons voir dans cet article.
Utilisez le langage approprié
L’extension « .md » vient du mot « markdown » : markdown un langage de balisage pour le formatage de texte, tout comme le HTML. Ce balisage permet de rendre nos documents présentables. Une fois familiarisé avec, vos fichiers README.md seront vraiment plaisants à lire.
Voici le guide officiel de Github pour le format Markdown, si vous avez besoin d’un petit rafraîchissement de mémoire. Et tant qu’on est là, voici le guide pour insérer des smileys.
Une entête basique qui décrit le projet
Évidemment, vous devez mettre le titre du projet accompagné d’une brève description de ce qu’il réalise. N’en faites pas des tonnes non plus, et restez dans les généralités. Toute information qui risque de changer, comme des règles fonctionnelles, ne doit pas figurer à ce stade.
Si possible, faites héberger votre projet et mettez en place une démo live. Vous pouvez ajouter un lien vers cette démo dans votre README.md : cela va intéresser beaucoup de gens qui ne se feront pas prier pour jouer avec votre démo ! Sans parler du fait que les recruteurs apprécieront également les projets accompagnés d’une démo. Cela montre que vos projets ne sont pas qu’un simple dépôt de code sur github, et que vous êtes vraiment sérieux.
Utilisez des images
Vous avez évidemment des images de votre projet en tête mais vos lecteurs pourraient avoir besoin de quelques photos de votre projet.
Mieux encore : si Github ne permet pas l’ajout de vidéos, le format .gif est supporté, vous pouvez donc y insérer une petite séquence animée de votre code en action !
Prérequis, installation, déploiement
Ici, vous allez commencer par lister les dépendances du projet, comme des librairies ou des drivers par exemple.
A la suite de la section où vous avez listé les dépendances, ajoutez une nouvelle liste : il s’agit d’y placer, dans l’ordre chronologique, les procédures d’installation. Il est inutile de trop entrer dans les détails, une simple liste suffit.
Une fois le projet installé et prêt à être développé, vous allez devoir, dans la majorité des cas, écrire quelques indications supplémentaires pour aider à la construction, la publication ou le déploiement du code en donnant des instructions claires (et de préférence à copier-coller).
Contribution
Chaque projet tend à avoir ses propres « meilleures pratiques », basées sur le travail de l’équipe de développeurs.
Le fichier README est le meilleur endroit pour y inclure une introduction rapide sur les conventions du projet, comme :
- Quel genre de style de code utiliser ?
- Comment écrire des commit et faire des branches ?
- Comment rester en contact avec l’équipe (irc, listes de diffusion, Slack, etc.) ?
Au mieux, il s’agit de quelques phrases courtes et d’un lien vers le guide des bonnes pratiques. C’est tout ce dont vous avez besoin.
Licences
L’octroi de licences pour les projets open-source, ainsi que leur absence, pose souvent problème.
L’un des points clés lors de la recherche d’un nouveau projet auquel contribuer est la propriété du code : Puis-je utiliser, modifier et contribuer au projet ? Puis-je utiliser le code qui en résulte dans mon travail ou dans mes projets ?
Vous devez répondre à ces questions en indiquant simplement la licence dont le projet est titulaire. Cela permet aux contributeurs de gagner du temps au lieu de devoir rechercher l’information dans votre projet et déterminer s’il y a quelque chose qui pourrait se retourner contre eux à l’avenir.
Badges
Les badges sur votre fichier README.md donnent au lecteur un sentiment d’authenticité, et les badges dynamiques aident à faire « vivre » votre fichier README.md, en indiquant de manière automatique toute une série d’informations utiles.
Il existe en effet de nombreux badges, dynamiques (nombre d’étoiles, de téléchargements, le pourcentage de traduction dans telle ou telle langue, etc) mais aussi des badges statiques (que vous pourriez par exemple utiliser pour indiquer la licence de votre projet).
Vous pouvez obtenir des badges personnalisés pour votre dépôt à l’adresse suivante : https://shields.io.
Vous détenez désormais les clés pour écrire un bon fichier readme.md qui accompagnera vos développements !
Vous recherchez de nouvelles missions freelances en développement ? Inscrivez-vous sur Codeur.com et répondez aux clients en recherche de prestataires !
Vous préférez confier vos développements à un professionnel ? Postez votre projet gratuitement sur Codeur.com et recevez de nombreux devis rapidement.
