Bonnes Pratiques Documentation | GitScrum
Créez et maintenez une documentation utile et à jour. GitScrum aide à construire des habitudes qui soutiennent votre processus de développement.
5 min de lecture
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 │
│ │
│ │
│ ## 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.