Traitez la documentation comme partie intégrante du changement
Lorsque le comportement change, le moment le plus fiable pour mettre à jour la documentation est la même pull request. Les relecteurs peuvent comparer l'implémentation et l'explication ensemble, et les étiquettes de version maintiennent la documentation alignée sur le code publié.
- Conservez un README ciblé près du composant qu'il explique.
- Exigez des mises à jour de la documentation lorsque le comportement public, la configuration ou les étapes opérationnelles changent.
- Utilisez des vérifications de liens et de style dans l'intégration continue.
- Attribuez une propriété claire aux runbooks à risque élevé et aux pages de référence.
Choisissez le type de document avant d'écrire
Un tutoriel enseigne à travers une séquence. Un guide pratique résout une tâche. Une documentation de référence décrit un comportement exact. Une explication apporte contexte et arbitrages. Mélanger les quatre dans un long README rend chacun plus difficile à utiliser.
Les enregistrements de décisions d'architecture constituent un autre motif utile : consignez le contexte, la décision, les alternatives et les conséquences pendant que le raisonnement est encore frais. Markdown maintient l'enregistrement près du code sans nécessiter un flux de publication distinct.
Rendez les exemples de code testables et honnêtes
Les lecteurs copient les exemples. Incluez les imports requis, des noms réalistes, la sortie attendue et le chemin d'erreur pertinent. Si l'extrait est volontairement incomplet, dites-le. Un petit exemple testé vaut mieux qu'un grand bloc qui semble seulement plausible.
```bash # Validate docs before opening a pull request npm run lint npm run typecheck ``` Expected result: both commands exit with status 0.
Optimisez pour des diff faciles à relire
Utilisez une phrase par ligne uniquement si le dépôt adopte cette convention de manière cohérente ; sinon, revenez à la ligne naturellement et laissez les outils gérer la présentation. Évitez de reformater un fichier entier lors d'une modification factuelle. Des titres stables et des liens de style référence peuvent rendre les grands documents plus faciles à modifier sans diff bruyants.
- Donnez aux titres des noms précis qui restent utiles dans les ancres générées.
- Gardez les tableaux étroits et évitez les cellules remplies de prose.
- Utilisez des liens relatifs pour les fichiers qui suivent le dépôt.
- Ne collez pas de secrets, de journaux privés ou de données de production non expurgées dans les exemples.
Utilisez la conversion comme point de départ d'une migration
Un fichier Word, une feuille de calcul, un PDF ou une présentation peut contenir des connaissances précieuses qui ne s'inscrivent pas encore dans un flux de travail docs-as-code. Le convertir en Markdown supprime une grande partie de la couche de présentation, mais un développeur doit encore normaliser les titres, réparer les liens, choisir les limites des fichiers et confirmer l'exactitude technique.
Conservez le document source jusqu'à ce que la version convertie ait été relue. Pour les données calculées ou les documents signés, l'original peut rester la source de vérité même après l'ajout d'un instantané Markdown lisible au dépôt.