Sous l’angle des équipes agiles, la documentation évolue vers une logique vivante et collaborative. Elle se conçoit comme code lisible, tests vivants et conversations productives entre métiers et développeurs.
Ces repères traitent de wikis, bases de connaissances et standards pratiques pour des équipes réelles. Je présente ensuite les éléments essentiels regroupés sous la rubrique A retenir :
A retenir :
- Fiabilité des contenus et correspondance constante avec le logiciel livré
- Effort minimal grâce à automatisation des extraits et réconciliation
- Collaboration inter-disciplinaire et conversations structurées pendant les ateliers
- Documents vivants testables et apprentissage intégré pour nouveaux venus
Wikis et bases de connaissances pour documentation vivante : DokuWiki, MediaWiki, Confluence
Après ces points synthétiques, examinons les différences entre wikis et bases de connaissances. Ces différences orientent le choix entre DokuWiki, MediaWiki, Confluence ou Notion selon le contexte et la maturité des équipes.
Différences structurelles et usages
Cette analyse porte sur l’architecture, le modèle d’édition et la scalabilité des wikis et KB. MediaWiki alimente Wikipédia et privilégie le contenu public encyclopédique, avec une forte communauté. DokuWiki reste apprécié pour les installations internes simples et sa gestion de fichiers sans base de données.
Critères pratiques de choix :
- Complexité projet et besoin d’extensions
- Maturité de l’équipe et tolérance à la maintenance
- Contraintes réglementaires et traçabilité des changements
- Intégration avec outils de gestion comme Redmine ou Jira
Outil
Type
Force principale
Cas d’usage
MediaWiki
Open source wiki
Optimisé pour contenu encyclopédique
Documentation publique et collaborative (Wikipédia)
DokuWiki
Open source fichier-plat
Installation simple, faible overhead
Wikis internes techniques et notes d’équipe
Confluence
Commercial / SaaS
Intégration forte avec Jira et enterprise
Base de connaissances orientée entreprise
Notion
SaaS workspace
Blocs flexibles pour documentation légère
Guides d’équipe, didacticiels et pages produit
Cette carte des outils éclaire les implications pratiques pour les équipes. XWiki ou Read the Docs peuvent intervenir selon contrainte d’hébergement, sécurité ou format ciblé.
Choisir selon projet et taille
Ce choix dépend principalement de la taille du projet, des exigences réglementaires et des parties prenantes. Les petites équipes privilégieront la simplicité, tandis que les grands programmes favoriseront l’intégration et la gouvernance centralisée.
« J’ai migré notre wiki vers Confluence pour gagner en traçabilité et intégration avec Jira, la différence a été nette »
Claire N.
Cas d’usage recommandés :
- Wikis publics et collaboratifs pour communautés ouvertes
- KB d’entreprise intégrée à outils de devops
- Notes et process légers dans Notion ou Zettlr
- Documentation technique hébergée sur Read the Docs
Documentation vivante et automatisation : principes, tests et outils
La question de l’automatisation découle du choix des outils et des modèles documentaires utilisés. Selon Martraire, la « documentation vivante » exige fiabilité, effort faible et propriété collective pour être efficace.
Principes et pratiques de la documentation vivante
Cette section reprend les principes clefs qui garantissent que la documentation reste alignée avec le logiciel livré. Selon Adzic, spécifier par exemples et automatiser la génération réduit les écarts entre texte et comportement.
Principes fondants :
- Fiabilité par synchronisation continue avec le code
- Faible effort grâce à l’automatisation et la réconciliation
- Collaboratif, discussions et ateliers partagés
- Apprentissage intégré pour faciliter l’onboarding
Principe
Description
Impact opérationnel
Fiabilité
Doc testée et référencée par les mêmes artefacts
Réduction des erreurs et divergence minimale
Faible effort
Automatisation des extraits et génération
Moins de travail manuel, meilleure réactivité
Collaboratif
Règles de propriété collective et conversations
Adhésion accrue et savoir partagé
Testable
Documentation générée à partir de tests exécutés
Validation continue de l’exactitude
« J’ai vu des tests Cucumber produire des extraits de doc utiles pour les équipes produit et QA »
Marc N.
Selon Fauvel, la génération de documentation à partir de scripts de tests permet d’identifier rapidement les divergences. Cette approche facilite l’exécution répétée et la réconciliation des sources d’information.
Automatisation technique et outils
Ce point traite des outils qui rendent la documentation vivante et maintenable au fil des versions. Les orchestrateurs CI/CD et les générateurs de doc sont centraux pour industrialiser la génération automatique.
Outils courants :
- Cucumber ou frameworks BDD pour produire exemples testables
- Read the Docs et Sphinx pour documentation versionnée
- Jenkins, GitLab CI ou Azure DevOps pour pipeline de génération
- OnlyOffice, Redmine, XWiki selon besoins collaboratifs
« Nous avons intégré Read the Docs à notre pipeline, la documentation suit maintenant chaque release »
Paul N.
Selon Martraire, l’automatisation réduit le coût d’entretien et augmente la confiance utilisateur. L’enjeu suivant est la gouvernance et l’adoption par les équipes humaines.
Gouvernance, modèles et apprentissage intégré pour standards de documentation
Ce passage aborde les règles et modèles nécessaires pour pérenniser une documentation vivante dans l’organisation. Selon Adzic, la formalisation par exemples facilite le dialogue entre métier et technique.
Modèles et conventions : LP, DDD et DoD
Cette partie détaille comment des modèles comme le Literate Programming et le Domain-Driven Design soutiennent la cohérence documentaire. Le DoD doit inclure la documentation comme critère d’acceptation pour chaque incrément.
Schémas de gouvernance :
- Langage omniprésent pour aligner vocabulaire métier et technique
- Records de décision d’architecture pour retracer choix et évolutions
- Processus de dépréciation automatisé pour retirer les documents obsolètes
- Ateliers réguliers pour maintenir la propriété collective
Adoption, formation et partage des connaissances
Ce volet insiste sur l’apprentissage intégré et les pratiques de facilitation visuelle pour diffuser les savoirs. Les formats low-tech, comme tableau blanc photographié puis archivé, restent pertinents pour des changements rapides.
« En formant nos nouvel·les arrivant·es sur la documentation et le code, l’onboarding est devenu beaucoup plus rapide »
Emma N.
Actions d’adoption :
- Sessions de pair programming et revues documentaires régulières
- Radiateurs d’information pour rendre visibles les changements récents
- Cartes d’impact pour prioriser la documentation à maintenir
- Maximes et guides rapides pour diffuser bonnes pratiques
Selon Fauvel, fusionner scripts de test et génération documentaire réduit les divergences observées en production. Ce modèle combine code, tests et documents pour un apprentissage continu.
Source : Gojko Adzic, « Specification by Example », 2011 ; Paul Otlet, « Traité de Documentation – Le Livre sur le Livre », 1934 ; Cyril Martraire, « Documentation vivante », 2019.
otoyoutube query= »Specification by Example Gojko Adzic »>