5 min lecture • Guide 644 of 877
Bonnes pratiques de documentation
Une bonne documentation accélère l'onboarding, réduit les silos de connaissances et évite les questions répétées. Les fonctionnalités de documentation de GitScrum aident les équipes à maintenir une documentation vivante aux côtés de leur travail de développement, garantissant que les docs restent à jour et accessibles.
Stratégie de documentation
Quoi documenter
PRIORITÉS DE DOCUMENTATION :
┌─────────────────────────────────────────────────────────────┐
│ DOIT DOCUMENTER : │
├─────────────────────────────────────────────────────────────┤
│ ✓ Démarrage / Instructions d'installation │
│ ✓ Vue d'ensemble de l'architecture │
│ ✓ Documentation API │
│ ✓ Options de configuration │
│ ✓ Procédures de déploiement │
│ ✓ Runbooks d'incident │
│ │
│ DEVRAIT DOCUMENTER : │
├─────────────────────────────────────────────────────────────┤
│ ○ Architecture Decision Records (ADRs) │
│ ○ Étapes de dépannage courantes │
│ ○ Processus et accords d'équipe │
│ ○ Checklist d'onboarding │
│ │
│ ENVISAGER DE NE PAS DOCUMENTER : │
├─────────────────────────────────────────────────────────────┤
│ ✗ Code évident (auto-documenté) │
│ ✗ Contournements temporaires (utiliser commentaires) │
│ ✗ Notes de réunion (sauf décisions) │
└─────────────────────────────────────────────────────────────┘
Types de documentation
STRUCTURE DE DOCUMENTATION :
┌─────────────────────────────────────────────────────────────┐
│ TYPE │ AUDIENCE │ OBJECTIF │
├───────────────┼──────────────┼──────────────────────────────┤
│ README │ Nouveaux devs│ Démarrage rapide, aperçu │
│ Docs API │ Consommateurs│ Comment utiliser le service │
│ Architecture │ Équipe │ Comment le système fonctionne│
│ ADRs │ Équipe/Futur │ Pourquoi décisions prises │
│ Runbooks │ Ops/Astreinte│ Comment répondre aux problèmes│
│ Tutoriels │ Nouveaux devs│ Apprendre la codebase │
│ Référence │ Tous devs │ Détails techniques complets │
└───────────────────────────────────────────────────────────────┘
Écrire des docs efficaces
Template README
STRUCTURE README STANDARD :
┌─────────────────────────────────────────────────────────────┐
│ # Nom du projet │
│ │
│ Description en une ligne de ce que ça fait. │
│ │
│ ## Démarrage rapide │
│ ```bash │
│ npm install && npm start │
│ ``` │
│ │
│ ## Prérequis │
│ - Node.js 18+ │
│ - PostgreSQL 14+ │
│ │
│ ## Installation │
│ Instructions d'installation étape par étape │
│ │
│ ## Configuration │
│ Variables d'environnement et options │
│ │
│ ## Développement │
│ Comment exécuter localement, tests, etc. │
│ │
│ ## Contribuer │
│ Comment soumettre des changements │
│ │
│ ## Licence │
└─────────────────────────────────────────────────────────────┘
Architecture Decision Records
TEMPLATE ADR :
┌─────────────────────────────────────────────────────────────┐
│ # ADR-001 : Utiliser PostgreSQL comme base principale │
│ │
│ ## Statut │
│ Accepté │
│ │
│ ## Contexte │
│ Nous avons besoin d'une base pour les données utilisateurs.│
│ Exigences : │
│ - Conformité ACID │
│ - Support JSON │
│ - Familiarité de l'équipe │
│ │
│ ## Décision │
│ Nous utiliserons PostgreSQL 14. │
│ │
│ ## Conséquences │
│ - L'équipe connaît déjà PostgreSQL │
│ - Bon écosystème d'outils │
│ - Devra gérer les mises à niveau │
│ │
│ ## Alternatives considérées │
│ - MySQL : Moins de support JSON │
│ - MongoDB : Équipe non familière │
│ │
│ Date : 2024-01-15 │
│ Auteurs : @marie, @jean │
└─────────────────────────────────────────────────────────────┘
Maintenir les docs à jour
Docs dans la définition de Done
DÉFINITION DE DONE FONCTIONNALITÉ :
┌─────────────────────────────────────────────────────────────┐
│ │
│ CODE COMPLET : │
│ □ Implémentation terminée │
│ □ Tests écrits │
│ □ Code revu │
│ │
│ DOCUMENTATION COMPLÈTE : │
│ □ Docs API mises à jour (si API changée) │
│ □ README mis à jour (si setup changé) │
│ □ Docs architecture mises à jour (si significatif) │
│ □ Runbooks mis à jour (si opérations affectées) │
│ │
│ PRÊT POUR DÉPLOIEMENT : │
│ □ Entrée changelog ajoutée │
│ □ Notes de release rédigées │
└─────────────────────────────────────────────────────────────┘
Cycle de revue de documentation
La documentation nécessite une maintenance régulière pour rester précise. Planifiez des revues trimestrielles pour identifier le contenu obsolète, valider les procédures et mettre à jour les exemples. GitScrum peut suivre ces tâches de revue aux côtés du travail de développement régulier.