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 et outils didactiques permettant de mesurer votre progrès et votre intégration des concepts par les participants sont utilisés tout au long de la formation.


Plusieurs méthodes d’apprentissage et outils didactiques permettant de mesurer le progrès et l’intégration des concepts par les participants 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

À savoir lorsque cette formation est en ligne

Nos formations en ligne sont diffusées sous forme de classes virtuelles interactives et nous travaillons avec la plateforme Zoom.

Vous devez avoir un ordinateur avec un bon accès à Internet ainsi qu'une caméra, un micro et des haut-parleurs afin de participer à la formation. Pour faciliter les échanges avec le formateur ou la formatrice et les autres participants et participantes, ainsi que pour être en mesure de participer au volet pratique de la formation, la caméra doit être fonctionnelle et ouverte tout au long de la formation, à défaut de quoi votre participation pourrait être refusée.

    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é

Avec plus de 30 années 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 a un bagage théorique et pratique très fort en expérience utilisateur/client/employé, en utilisabilité, en ergonomie cogni1ive 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 tout en restant centrée sur l’humain.