Documentation système 2.0 : Une documentation vivante

« La documentation est l’huile de ricin de la programmation. Les gestionnaires croient qu’elle doit être utile parce que les programmeurs la détestent. » ― Gerald M. Weinberg, The Psychology of Computer Programming

« Nous découvrons comment mieux développer des logiciels par la pratique et en aidant les autres à le faire. Ces expériences nous ont amenés à valoriser : […] Des logiciels opérationnels plus qu’une documentation exhaustive […] » — Manifeste pour le développement Agile de logiciels

La documentation est perçue comme un mal nécessaire. Lorsqu’elle est réalisée, elle est lourde, elle devient rapidement désuète ou elle n’est jamais plus consultée #TAGRI.

Dans un contexte d’agilité et de conformité, il est possible de produire une documentation utile et pertinente qui reflète la réalité tout en répondant aux exigences de conformité.

En faisant des liens très forts entre certains principes de conception pilotée par le domaine (Domain-driven Design - DDD) ainsi que les pratiques DevOps, cette formation est une introduction à la documentation système vivante. Sans expliquer toute la théorie derrière la connaissance relative à un système informatique, elle donne plusieurs recettes et méthodes heuristiques (c’est-à-dire des méthodes qui servent à la découverte) sur « pourquoi », « quoi », « comment », « où » et « quand » documenter et « qui » documente.

• Identifier les différents types de documentation et d’artéfacts documentaires
• Produire une documentation vivante
• Produire une documentation suffisante (juste assez) et juste à temps
• Produire une documentation au bon endroit et facile à trouver
• Décrire des modèles par des diagrammes descriptifs, dans un langage ubiquitaire (Ubiquitous Language)
• Rédiger des fiches de décisions d’architecture (Architectural Decision Record, ADR)
• Critiquer et valider la pertinence et la qualité de leur documentation en fonction du message, du public cible et des exigences normatives et réglementaires (conformité)

Concepts clés

• Introduction : Le problème avec la documentation traditionnelle
• Types de documentation
• Utilité de la documentation, objectifs et documentation responsable
• Introduction à la théorie de la communication et survol de la théorie concernant la création et la gestion de la connaissance
• Principes liés à la documentation vivante
• Séparation de la documentation entre les espaces « Problème », « Solution » et « Livraison »
• Anti-patrons de documentation vivante

Outils et formats

• Format et support de la documentation
• Fiches de décisions d’architecture (Architectural Decision Record, ADR) et son journal
• Introduction au modèle C4
• Relation avec un référentiel d'entreprise

Mises en situation

• Exemples de domaines de documentation et visualisations
• Éléments de documentation conforme

Conclusion

• Documentation vivante et pragmatique : une documentation utile, de qualité, pertinente, à jour, facile et rapide à écrire, facile à trouver
• Adoption, adhésion et premiers pas
• Transition de la documentation traditionnelle à la documentation vivante
• Mise en place graduelle d’un modèle de documentation, étape par étape

Architectes et concepteurs.trices (fonctionnels ou logiciel), analystes, développeurs.euses, pilotes, toute autre personne qui a à rédiger de la documentation en lien avec le développement logiciel et ScrumMaster / chargé.e de projet qui veut encadrer son équipe par rapport à la documentation

Cette formation existe dans plusieurs formules (abrégée ou enrichie) selon le degré de profondeur et les exercices inclus dans la formation. Contactez-nous pour en savoir plus.