Documentation système 2.0 : une documentation vivante

Description de la formation

« 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.

Objectifs pédagogiques

À la fin de cette formation, vous serez en mesure de :

  • 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é)

Méthodologie

Plusieurs méthodes d’apprentissage permettant de mesurer votre progrès et votre intégration des concepts sont utilisés tout au long de la formation :

Clientèle visée

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

    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 : Intention, KISS, DRY, #NoDocumentation * Documentation fiable, à effort minimal, collaborative et instructive * Langage ubiquitaire standardisé
    • Séparation de la documentation entre les espaces « Problème », « Solution » et « Livraison » : Artéfacts documentaires types d’un système * Responsabilités des membres de l'équipe face à la documentation
    • Anti-patrons de documentation vivante

    Outils et formats

    • Format et support de la documentation : Documentation in situ : carnets de produit, dépôt de code source, espaces de collaboration, etc. * Concepts et exemples de Documentation as Code * Introduction à Markdown * Outils de création de diagrammes (Diagrams as Code)
    • Fiches de décisions d’architecture (Architectural Decision Record) et son journal
    • Introduction au modèle C4

    Mises en situation

    • Exemples de domaines de documentation et visualisations
    • Fonctionnalités, éléments du carnet de produit comme les épopées, les récits, et les anomalies (Product - Backlog Item (epics, stories, bugs)),
    • Exigences techniques ou non fonctionnelles (Non-Functional Requirements) et éléments de sécurité
    • Parcours utilisateurs (journey) vs Story Mapping
    • Architecture émergente, solution changeante au gré des récits utilisateur, confirmation du besoin par des représentations à basse fidélité (wireframe)
    • Modèles pertinents
    • É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
Éric Chartré

Éric Chartré

Possédant plus de 30 ans d’expérience, Eric Chartré est un expert-généraliste en architecture de solution, en conception logicielle, en ingénierie logicielle et en gestion de la connaissance. De plus, il détient un bagage théorique et pratique très fort en expérience utilisateur/client/employé, en utilisabilité, en ergonomie cognitive et en sécurité. Ses connaissances et son expérience sont couplées à une pensée agile, réaliste, pragmatique, originale et, parfois, perturbatrice, principalement axée sur l’innovation et la méthode scientifique, mais tout en restant centrée sur l’humain.

Collaborateur

ELAPSE