RETOUR
On dit que lorsque nous rencontrons quelqu'un pour la première fois, la première impression est la plus importante. Il en va de même pour le dépôt de code d'un projet. Un README bien rédigé est crucial non seulement pour les développeurs actuels, mais aussi pour les futurs. Il présente le projet et fournit des instructions étape par étape qui permettent une installation et une contribution rapides.
Il doit contenir tous les aspects que le développeur a besoin de connaître et qui ne peuvent pas être reçus directement de l code. Ils incluent les choses à faire et à ne pas faire en matière de développement, des instructions complètes de déploiement, des descriptions d'intégration externe, et ainsi de suite. Ce billet vous guidera dans la création d'un fichier README puissant, beau et lisible pour votre projet.
Une bonne introduction pour une documentation de projet bien préparée peut être trouvée sur les guides github : https://guides.github.com/features/wikis/. Il stipule que "le README ne doit contenir que les informations nécessaires aux développeurs pour qu'ils puissent commencer à utiliser le projet et à y contribuer".
Dans cette optique, nous allons présenter une liste de composants et de bonnes pratiques que nous suivons chez Codest pour créer la documentation d'un projet.
- Titre du projet: il s'agit d'un élément indispensable à tout README.
- Badges de statutsi vous utilisez des mesures externes de la qualité du code, des tests automatisés ou d'autres outils, le début du document est un bon endroit pour montrer aux autres s'ils fonctionnent.
- DescriptionLe projet doit être présenté en quelques phrases afin d'en décrire rapidement l'objectif principal et l'utilité.
Une liste de contenu peut être utile pour les longs fichiers de documentation, mais si votre README est assez concis, elle n'est pas nécessaire.
- A propos de la sectiondescription du projet : il s'agit d'une description plus détaillée du projet - elle peut inclure des informations sur les utilisateurs, leurs rôles, des cas plus complexes, des captures d'écran, etc.
- Maquettes: une place pour les liens vers des ressources de maquettes UI/UX s'il y en a.
- Exigences: conditions préalables qui doivent être remplies avant de commencer l'installation d'une application, par exemple l'installation d'outils externes.
- Mise en placeun mode d'emploi étape par étape à suivre pour mettre en œuvre le projet.
- ParamètresL'article 3.1.1. décrit l'endroit où les paramètres locaux sont stockés et fournit des instructions sur la manière de recevoir vos propres paramètres.
- Configuration localeSi des cas se présentent pour l'installation locale, c'est un bon endroit pour une explication.
Cette section est l'endroit idéal pour les instructions telles que le développement de fonctionnalités, les corrections de bogues, les correctifs, les fonctionnalités communes, les tests, les guides de style, l'organisation du code, les autres outils de développement utilisés dans le projet (par exemple, guards ou dockers), et ainsi de suite. N'oubliez pas de mentionner toutes les règles que chaque équipe doit savoir.
Fournir des instructions claires, étape par étape, pour chaque environnement et tout ce qu'il est "bon de savoir" lors du déploiement.
- Documentation de l'API
- Changelog
- Ressources externes: un endroit pour toutes sortes de liens qui peuvent être utiles.
- Pile d'applications: une liste de la pile d'applications que nous utilisons dans le projet - peut contenir une brève description et le nom du fournisseur.
On peut se demander s'il est nécessaire d'afficher les membres actuels de l'équipe du projet (github fournit par défaut la liste complète des contributeurs), mais il est toujours agréable de voir son nom figurer parmi les auteurs d'un projet. Si vous le faites, tenez-le à jour autant que possible.
N'oubliez pas que chaque projet est unique et qu'il en va de même pour sa documentation. Il n'y a pas de solution unique pour écrire un README. Il suffit de suivre les conseils généraux, et la chose la plus importante est de toujours se souvenir du refactoring, qui est également lié au README. C'est toujours une bonne idée de regarder le document dans son ensemble et de le repenser si quelque chose doit être présenté d'une manière différente.
Une dernière chose : les "instructions" sont essentielles, alors écrivez-les souvent. Merci de votre attention !
En savoir plus :
French 
English 
German 
Swedish 
Danish 
Norwegian 
Finnish 
Polish 
Arabic 
Italian 
Japanese 
Korean 
Spanish 
Dutch 
Estonian 
Greek