Article original : How to Write a Good README File for Your GitHub Project
Lorsque j'ai été introduit à GitHub pour la première fois, je n'avais aucune idée de ce que c'était ou de ce qu'il pouvait faire. Entre vous et moi, j'ai créé le compte parce qu'on m'a dit que chaque développeur devrait en avoir un où ils poussent leur code.
Pendant très longtemps, en tant que débutant, je n'ai rien fait avec mon compte. Mais ensuite, grâce à ma passion pour la technologie, j'ai commencé à suivre d'autres développeurs et à vérifier leur travail sur GitHub. Et j'ai remarqué quelque chose qu'ils avaient en commun : ils avaient tous des projets cool et contribuaient à l'open source, mais leurs projets avaient également des fichiers README détaillés.
Mon intérêt pour ce qu'était un README a donc grandi, et j'ai décidé d'essayer d'en ajouter un dans mes projets aussi. Je ne vais pas mentir – je l'ai fait à la hâte sans aucune connaissance de la manière dont cela devrait être fait. Et honnêtement, ce n'était pas du tout génial. Vérifiez-le ICI.
Et c'est ainsi que cela est resté pendant un certain temps. Mais avec la pratique et l'apprentissage continu, j'ai pu passer à une meilleure documentation comme CECI, ce qui a amélioré l'engagement avec le projet et aidé d'autres développeurs à s'impliquer.
Il est également important de noter qu'un bon README vous aidera à vous démarquer parmi la grande foule de développeurs qui mettent leur travail sur GitHub.
Dans cet article, nous allons en apprendre davantage sur ce qu'est un fichier README et comment en écrire un. Commençons par comprendre ce que nous entendons par un fichier README.
Qu'est-ce qu'un fichier README ?
En termes simples, nous pouvons décrire un fichier README comme un guide qui donne aux utilisateurs une description détaillée d'un projet sur lequel vous avez travaillé.
Il peut également être décrit comme une documentation avec des directives sur la façon d'utiliser un projet. Habituellement, il contiendra des instructions sur la façon d'installer et d'exécuter le projet.
Il est essentiel pour vous, en tant que développeur, de savoir comment documenter votre projet en rédigeant un README parce que :
- C'est le premier fichier qu'une personne verra lorsqu'elle rencontrera votre projet, donc il devrait être assez bref mais détaillé.
- Il fera ressortir votre projet parmi un tas d'autres. Assurez-vous également que votre projet est bon.
- Il vous aidera à vous concentrer sur ce que votre projet doit livrer et comment.
- Il améliorera vos compétences en rédaction, comme l'a dit Friedrich Nietzsche :
Un bon écrivain possède non seulement son propre esprit, mais aussi l'esprit de ses amis.
En travaillant sur un projet, gardez à l'esprit que vous aurez besoin que d'autres développeurs comprennent votre code et ce qu'il fait. Donc l'accompagner d'un guide supplémentaire sera vraiment utile.
Par exemple, mon exemple précédemment partagé de mon premier projet n'a pas un bon README. Et même si le projet était génial, il aurait été difficile pour un débutant de comprendre exactement ce qui était attendu lorsqu'ils clonent mon dépôt. Qui sait, peut-être que cela aurait même pu être un virus codé.
Avec un projet comme celui-ci sur GitHub, peu importe à quel point il est génial, d'autres développeurs ne seront pas impatients de travailler dessus et d'essayer de le comprendre sans un bon README.
Maintenant, jetez un coup d'œil à ce projet. Ici, vous êtes en mesure de comprendre ce que fait le projet, ce qu'il implique, et comment commencer si vous devez l'utiliser ou si vous souhaitez contribuer au projet.
Vous voyez, c'est à quel point un README bien rédigé est puissant et comment il peut changer votre projet.
Alors, commençons à apprendre comment en écrire un pour vous aussi.
Comment écrire un bon README – un guide étape par étape
Une chose très importante à noter est qu'il n'y a pas une seule bonne façon de structurer un bon README. Mais il y a une très mauvaise façon, et c'est de ne pas inclure de README du tout.
D'après mes recherches et l'étude de divers fichiers README, il y a certainement quelques bonnes pratiques que j'ai trouvées. Et c'est ce que je vais partager. Comme je me le dis souvent :
Chaque jour est un jour d'apprentissage.
Ainsi, à mesure que vous progressez et avancez dans votre carrière, vous développerez vos propres idées sur ce qui fait un bon README et comment l'améliorer. Peut-être que vous inventerez même votre propre guide unique.
Avant de commencer, il est également important de noter que lorsque vous écrivez le README de votre projet, il doit être capable de répondre au quoi, pourquoi, et comment du projet.
Voici quelques questions directrices qui vous aideront :
- Quelle était votre motivation ?
- Pourquoi avez-vous construit ce projet ?
- Quel problème résout-il ?
- Qu'avez-vous appris ?
- Qu'est-ce qui rend votre projet unique ? Si votre projet a beaucoup de fonctionnalités, envisagez d'ajouter une section "Fonctionnalités" et de les lister ici.
Que inclure dans votre README
1. Titre du projet
C'est le nom du projet. Il décrit l'ensemble du projet en une phrase et aide les gens à comprendre quel est l'objectif principal et le but du projet.
2. Description du projet
C'est un composant important de votre projet que de nombreux nouveaux développeurs négligent souvent.
Votre description est un aspect extrêmement important de votre projet. Une description bien rédigée vous permet de montrer votre travail à d'autres développeurs ainsi qu'à des employeurs potentiels.
La qualité d'une description README différencie souvent un bon projet d'un mauvais projet. Une bonne description tire parti de l'opportunité d'expliquer et de présenter :
- Ce que fait votre application,
- Pourquoi vous avez utilisé les technologies que vous avez utilisées,
- Certains des défis auxquels vous avez été confronté et des fonctionnalités que vous espérez implémenter à l'avenir.
3. Table des matières (Optionnel)
Si votre README est très long, vous pouvez ajouter une table des matières pour faciliter la navigation des utilisateurs vers différentes sections. Cela facilitera la navigation des lecteurs dans le projet.
4. Comment installer et exécuter le projet
Si vous travaillez sur un projet qu'un utilisateur doit installer ou exécuter localement sur une machine comme un "POS", vous devez inclure les étapes nécessaires pour installer votre projet ainsi que les dépendances requises, le cas échéant.
Fournissez une description étape par étape de la manière de configurer et d'exécuter l'environnement de développement.
5. Comment utiliser le projet
Fournissez des instructions et des exemples afin que les utilisateurs/contributeurs puissent utiliser le projet. Cela leur facilitera la tâche en cas de problème – ils auront toujours un endroit où se référer à ce qui est attendu.
Vous pouvez également utiliser des aides visuelles en incluant des matériaux comme des captures d'écran pour montrer des exemples du projet en cours d'exécution ainsi que la structure et les principes de conception utilisés dans votre projet.
De plus, si votre projet nécessitera une authentification comme des mots de passe ou des noms d'utilisateur, c'est une bonne section pour inclure les identifiants.
6. Inclure les crédits
Si vous avez travaillé sur le projet en équipe ou au sein d'une organisation, listez vos collaborateurs/membres de l'équipe. Vous devez également inclure des liens vers leurs profils GitHub et leurs réseaux sociaux.
De plus, si vous avez suivi des tutoriels ou référencé un certain matériel qui pourrait aider l'utilisateur à construire ce projet particulier, incluez des liens vers ceux-ci ici également.
Ce n'est qu'une façon de montrer votre appréciation et aussi d'aider les autres à obtenir une copie de première main du projet.
7. Ajouter une licence
Pour la plupart des fichiers README, cela est généralement considéré comme la dernière partie. Cela permet aux autres développeurs de savoir ce qu'ils peuvent et ne peuvent pas faire avec votre projet.
Nous avons différents types de licences selon le type de projet sur lequel vous travaillez. Selon celle que vous choisirez, cela déterminera les contributions que votre projet recevra.
La plus courante est la licence GPL qui permet aux autres de modifier votre code et de l'utiliser à des fins commerciales. Si vous avez besoin d'aide pour choisir une licence, consultez ce lien : https://choosealicense.com/
Jusqu'à ce point, ce que nous avons couvert sont les exigences minimales pour un bon README. Mais vous pourriez également vouloir considérer l'ajout des sections suivantes pour le rendre plus attrayant et interactif.
Sections supplémentaires du README
8. Badges
Les badges ne sont pas nécessaires, mais les utiliser est un moyen simple de faire savoir aux autres développeurs que vous savez ce que vous faites.
Avoir cette section peut également être utile pour lier des outils importants et montrer quelques statistiques simples sur votre projet comme le nombre de forks, de contributeurs, de problèmes ouverts, etc...
Ci-dessous une capture d'écran de l'un de mes projets qui montre comment vous pouvez utiliser des badges :
Le bon côté de cette section est qu'elle se met à jour automatiquement.
Vous ne savez pas où les obtenir ? Consultez les badges hébergés par shields.io. Ils ont une tonne de badges pour vous aider à commencer. Vous ne comprendrez peut-être pas ce qu'ils représentent tous maintenant, mais vous le comprendrez avec le temps.
9. Comment contribuer au projet
Cela sera surtout utile si vous développez un projet open-source auquel vous aurez besoin que d'autres développeurs contribuent. Vous voudrez ajouter des directives pour leur faire savoir comment ils peuvent contribuer à votre projet.
Il est également important de s'assurer que la licence que vous choisissez pour les projets open-source est correcte afin d'éviter les conflits futurs. Et l'ajout de directives de contribution jouera un grand rôle.
Certaines des directives les plus courantes incluent le Contributor Covenant et le Guide de contribution. Ces documents vous donneront l'aide dont vous avez besoin lors de l'établissement de règles pour votre projet.
10. Inclure des tests
Allez plus loin et écrivez des tests pour votre application. Ensuite, fournissez des exemples de code et comment les exécuter.
Cela aidera à montrer que vous êtes certain et confiant que votre projet fonctionnera sans aucun problème, ce qui donnera également confiance aux autres personnes.
Points supplémentaires
Voici quelques points supplémentaires à noter lorsque vous écrivez votre README :
- Gardez-le à jour - Il est bon de s'assurer que votre fichier est toujours à jour. En cas de changements, assurez-vous de mettre à jour le fichier si nécessaire.
- Choisissez une langue - Nous venons tous de zones différentes et nous parlons tous des langues différentes. Mais cela ne signifie pas que vous devez traduire votre code en langage vernaculaire. Rédiger votre README en anglais fonctionnera puisque l'anglais est une langue globalement acceptée. Vous pourriez vouloir utiliser un outil de traduction ici si votre public cible n'est pas familier avec l'anglais.
Conclusion
Vous avez maintenant tout ce dont vous avez besoin pour améliorer vos fichiers README, ou même pour commencer à écrire votre premier.
À ce stade, je suis confiant que vous êtes en mesure d'ajouter un guide interactif et informatif à votre prochain projet ou même à un projet existant et de faire ressortir votre projet.
Il existe de nombreux outils que vous pouvez également utiliser pour générer automatiquement un README pour votre projet, mais il est toujours bon de l'essayer vous-même avant de passer à l'automatisation. Au cas où vous voudriez les vérifier, ils incluent :
Si vous avez lu jusqu'ici, je vous en suis vraiment reconnaissant. Si vous avez apprécié cet article et l'avez trouvé utile, veuillez le partager pour aider un autre développeur à améliorer ses projets.
J'adorerais voir votre nouveau fichier README. N'oubliez pas de partager un lien avec moi via l'un des liens ci-dessous :
Connectez-vous avec moi sur Twitter | YouTube | LinkedIn | GitHub
N'hésitez pas à partager votre opinion précieuse, j'apprécie vos commentaires honnêtes !
Bon codage ❤️