Documentation du projet

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.

Présentation rapide

- 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é.

Table des matières

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.

Informations générales

- 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.

• D'autres informations telles que Accès aux serveurs ou Intégration avec des API externesExemples : adresse url d'une instance de stockage, identifiants d'accès partagés non sensibles ( !), liens vers la documentation, certaines instructions, etc.

Installation

- 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.

Développement

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.

Déploiement

Fournir des instructions claires, étape par étape, pour chaque environnement et tout ce qu'il est "bon de savoir" lors du déploiement.

Autres idées de sections séparées

- 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.

L'équipe

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.

Quelques mots pour conclure

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 :

• Principe d'ouverture-fermeture. Dois-je l'utiliser un jour ?
• Comment écrire un code de qualité ?
• Vuelendar. Un nouveau projet de Codest basé sur Vue.js