Living Documentation

Description

La documentation est une tentative de répondre à certains besoins de partage en fonction du contexte du projet. Parmi les facteurs qui influencent ce besoin, la taille du projet est majeure, tout comme les besoins réglementaires ou les exigences des clients. Ce besoin peut également être atténué par l'expérience des équipes et les outils qui permettent de transférer les connaissances dans l'espace et dans le temps.

‍

Les modèles Waterfall et Agility ont des attitudes différentes vis-à-vis de la documentation.

Avec les soi-disant "méthodologies de développement rigoureuses" [Clear 2016], généralement promues par le modèle Waterfall, les incohérences dans la gestion de la configuration émergent de ces " expériences de pensée " ; malheureusement, cette approche conduit culturellement à un tas d'hypothèses qui sont vérifiées à la hâte vers la fin du projet. En fait, le principe sous-jacent de l'approche guidée par les documents devrait être de faire produire de la documentation en ligne à partir des moyens tangibles des utilisateurs finaux pour tester les hypothèses dès que possible [Clear 2016] [Moustier 2019-1].

L'agilité favorise les interactions plutôt que la documentation [Beck 2001], avec autant de rigueur que nécessaire [Rüping 2005] [Martraire 2019] et que l'équipe peut supporter [Moustier 2019-2]. L'agilité est en fait notamment basée sur la théorie de la construction de Peter Naur (voir https://pages.cs.wisc.edu/~remzi/Naur.pdf), l'équipe de programmation développe une "théorie du monde" qu'elle s'approprie conjointement pour se figer en logiciel ; le code est donc le principal artefact et la source primaire de documentation du projet [Clear 2016] [Beck 2004] avec une technique de partage implicite de ce qui a déjà été fait, la stigmergie [Martraire 2019], qui est le terme scientifique pour mimer les travaux précédents.

‍

Alors que le terme "documentation" est apparu à la fin du XIXe siècle ( voir https://www.cnrtl.fr/etymologie/documentation), le concept a été formalisé à partir du livre "Traité de Documentation - Le Livre sur le Livre - Théorie et Pratique" de Paul Otlet en 1934 qui décrivait cette discipline émergente pour traiter essentiellement les références bibliographiques. A partir de cette première formalisation, des divergences culturelles entre les pays sont apparues pour finalement être nommée "Information Science" dans la culture anglaise au lieu d'une simple liste de documents [Ortega 2009]. Cette absence de consensus sur le concept lui-même reflète sa polyvalence et sa complexité. 

‍

En ce qui concerne le lien entre la documentation et le code, Knuth a lancé une initiative appelée"Literate Programming" (LP) à partir du projet TEX dans les années 1980 [Guravage 2000]. La LP consiste en une "manière d'exposer et d'élucider la conception d'un programme en présentant ses parties dans un ordre et à un niveau d'abstraction qui privilégie la compréhension". 

LP répond à 3 propriétés [Guravage 2000].

• une source unique de programme lettré qui, lorsqu'elle est traitée, produit à la fois un programme exécutable et un document joliment typé
• un programme alphabétisé doit présenter un ordre de présentation flexible.
• un programme lettré, et les outils qui le traitent, devraient faciliter la génération automatique de références croisées, d'index et d'une table des matières

LP fait ressembler le code à un livre. De nos jours, ce courant est plutôt lié à l'approche "Clean Code" [Martin 2008].

‍

La "documentation vivante" (DL) est un concept qui a été largement promu par Cyril Martraire(https://www.youtube.com/watch?v=Tw-wcps7WqU) qui trouve ses origines dans le livre "Specifications by Examples" de Gojko Adzic [Adzic 2011]. Il s'agit d'une réponse à la citation de Gerald Weinberg 

"La documentation est l'huile de ricin de la programmation.
Les managers pensent que c'est bon pour les programmeurs et les programmeurs la détestent !"

Les principes fondamentaux de la DL sont [Martraire 2019] :

• Fiabilité en garantissant que toute la documentation est exacte et alignée sur le logiciel livré, à tout moment.
• Faible effort en minimisant la quantité de travail à effectuer sur la documentation sans aucune répétition des connaissances.
• Collaboratif en favorisant les conversations et le partage des connaissances entre les personnes concernées.
• perspicace, en attirant l'attention sur les éléments pertinents et en encourageant le retour d'information et une réflexion plus approfondie afin de prendre de meilleures décisions.

Ces principes déduisent plusieurs caractéristiques telles que [Martraire 2019].

• Une source unique pour les documents (par exemple dans le code)
• Un mécanisme de réconciliation pour extraire les données de plusieurs endroits (par exemple, les tests générés par BDD).
• Conversations sur la documentation
• Une propriété collective, qui s'appuie sur l'idéation de produits en groupe.
• Apprentissage intégré : chaque document, même le code, est si bon que les nouveaux venus peuvent apprendre en le lisant et en exécutant les tests correspondants.
• et bien sûr une documentation testable automatiquement.

‍

Le principe des "Conversations sur la documentation" est évidemment aligné sur le manifeste agile [Beck 2001]. Il est particulièrement pertinent lorsque le taux de changement des connaissances est élevé [Martraire 2019] ; de plus, il apparaît qu'après 1 an, moins de 1% des documents sont encore utilisés [Ortega 2009]. Les discussions sont également préférables lorsque le sujet est complexe et que des souches de documents peuvent être générées pour comprendre le contenu final prévu [Jan 2013].

‍

‍

‍

Cette approche basée sur le stub est facilitée par l'implication des affaires des personnes au sein de l'équipe. Plus cette implication est asynchrone avec l'équipe, plus les documents doivent être formels [Jan 2013].

‍

L'automatisation et les outils sont largement intégrés dans LD. Ils permettent de générer des documents à partir de tessons de documentation pour [Martraire 2019] [Hargis 2004] [Pelclová 2014] [Cockburn 2006].

• cibler les publics visés
• les rendre accessibles 
• maintenir les relations avec d'autres documents 

La documentation automatisée fait partie du cycle de la DL au même titre que [Martraire 2019].

• Gestion "sans documentation" - pratiques de partage des connaissances tacites telles que la programmation en binôme.
• Documentation stable - l'"intention de la solution" de SAFe [SAFe 2021-47] illustre cette préoccupation.
• Refactoring-Friendly documentation - Clean code, colocation, LP sont des aides dans cette partie du cycle.
• Documentation du temps d'exécution - notamment avec les annotations de code et le DSL, les calculs visibles et les tests.
• "Au-delà de la documentation" - traite notamment de l'apprentissage et de la transparence en matière d'hygiène

‍

Pour soutenir l'automatisation, les outils sont inévitables. Par exemple, vous pouvez inclure :

• BDD implique un outil de type Cucumber
• Certains langages, comme Java, permettent de faire des annotations, ce qui peut être utilisé pour construire un glossaire [Fauvel 2020]. Ils sont également capables d'un mécanisme de réflexion pour analyser le code dans le code lui-même.
• Les restituteurs de graphiques pour acquérir / vérifier visuellement certaines informations - Graphiz étant souvent utilisé pour générer des graphiques
• Générateurs de documents tels que QDox, CukeDoctor, YeST, outils basés sur le balisage (DocBook, DITA, HTMLBook, AsciiDoc, Wiki, Markdown, ...) ou systèmes propriétaires (Adobe, MadCap Flare, Confluence, ...)
• Des orchestrateurs tels que Jenkins, Gitlab-ci, Bamboo, Azure DevOps peuvent être utilisés pour scripter la génération automatique de la documentation.

Maintenant, le nom du jeu est "Trouver les outils appropriés et les coller pour construire la documentation".

Ce jeu implique de nombreux acteurs, points de vue et maturité pour y parvenir. Il ne peut pas être l'effort d'une seule personne notamment parce que LD infère des conventions en raison des outils impliqués.

Impact sur la maturité des tests

Plusieurs auteurs affirment que chaque projet décide de la documentation nécessaire [Ambler 2002] [Hoda 2012]. Dans le prolongement, l'agilité laisse généralement les gens gérer la documentation en tant qu'équipes auto-organisées, ce qui est cohérent avec le principe de décentralisation de la prise de décision.

Malheureusement, cette approche introduit un biais culturel avec des personnes qui se lassent de remplir leurs spécifications d'exigences. Par conséquent, les équipes dépendent fortement d'un soutien de la haute direction comme guide dans les méthodes agiles [Hoda 2012] qui peut être soutenu par un bon Scrum Master et/ou Product Owner. La direction agit notamment comme un facilitateur sur les interactions avec les tiers tels que les équipes Ops ou les fournisseurs et clients (internes et externes). Cette conscience de la bienveillance de l'environnement de l'équipe conduit généralement l'équipe à améliorer son Definition of Done (DoD).

‍

Pour être efficace dans la documentation du projet, les documents sont généralement modélisés [Ambler 2002].

• de communiquer (processus, transfert ou transfert de responsabilités) 
• comprendre et pouvoir aborder les processus, toute partie de l'idéation (marketing, spécifications, architecture ou code)
• ou pour soutenir la réflexion associée à chaque étape du projet

Pour assurer une certaine cohérence entre tous ces documents, viser une Langage omniprésent est alors la clé pour retrouver le même vocabulaire partout où le même contexte existe.

‍

Pour gagner en efficacité, il est possible d'expérimenter certains schémas [Martraire 2019].

Modèles d'ingénierie :

• "Créer un exemple concret ensemble, tout de suite, pendant cette réunion" : construire des documents en atelier évite les mails ping-pong et chaque participant connaît et s'accorde sur son contenu - exemples : 3 Amigos, Pair Programming, Mob Programming, Event Storming / Model Storming [Brandolini 2015] [Moustier 2020]
• "Générer à partir de code statique: le code et les scripts de construction sont accompagnés d'une documentation, notamment par le biais d'un processus de nommage [Belshee 2019], afin d'accroître la lisibilité du code conformément au paradigme LP. À partir de cette base, les documents peuvent être agrégés par la manipulation de la compilation, ce qui fait des documents du code ( voir https://www.writethedocs.org/guide/docs-as-code/). 
• "Générer à partir de code exécuté" : il peut s'agir d'états de flux de travail [Fauvel 2020] ou de tests exécutés qui génèrent des journaux lisibles sur rapport de tests (voir le code de Sébastien FAUVEL sur LD : https://sfauvel.github.io/documentationtesting/ + https://github.com/sfauvel/livingdocumentation).
• "Fournir des connaissances utiles" : contenus flexibles et axés sur les objectifs [Fauvel 2020], tels que des didacticiels, des modes d'emploi, des explications ou un catalogue de référence, avec des parties qui peuvent être sautées pour permettre au "lecteur" d'atteindre rapidement les parties inconnues ; les différences mises en évidence par rapport aux versions précédentes ou les parties connexes répondent également à ce modèle.
• "Low-Fidelity" : inviter les gens à ajouter leurs contributions pour consolider les connaissances dans un état d'esprit " juste assez de documentation " [Hoda 2012] [Jan 2013].
• "Low-Tech" : les supports rapides tels que les tableaux blancs dont le dessin est capturé par une photo sont plus flexibles que le dessin basé sur des outils, ce qui facilite les changements - à un certain point de basculement, les outils deviennent inévitables, de même que les informations stables.
• "Enregistrer les changements: documenter les décisions de changement sur les wikis avec des horodateurs et des mécanismes de réconciliation [Hoda 2012] pour reconstruire l'image finale, comme le mécanisme d'approvisionnement par événement [Fowler 2005] [Moustier 2020] ou les registres de décisions d'architecture (voir ici https://github.com/joelparkerhenderson/architecture-decision-record). 

‍

Modèles de refactoring :

• "Contexte de bulle" : le principe de décentralisation de la prise de décision est appliqué pour isoler certaines connaissances et protéger certains changements.
• "Appliquer 5S": la documentation reste propre
• "Approche de type DDD-like approach" : structure la documentation à partir des perspectives commerciales et techniques.
• "Archéologie" : la pratique de l'archéologie doit être facilitée par des cartes du terrain rendues possibles par des annotations, des tags, des résumés, des modèles...
• "Transformation biodégradable" : une fois le processus de transformation terminé, le document est retiré.
• "Enforced Legacy Rules" : l'automatisation des règles avec des mécanismes de déprécation soutient les efforts des gens

Des modèles de partage :

• "Facilitation visuelle" : les dessins sont plus rapides à saisir que les textes
• "Yokoten" : pratique de partage transversal ; notamment inclus dans certaines rétrospectives
• "Maximes pour diffuser des principes" : directives formulées sous forme de punchlines faciles à mémoriser pour être naturellement diffusées et répétées (par exemple, "Ne nourrissez pas le monstre", "A Rome, faites comme les Romains", ...).
• "Points forts" : FAQ, condensés de connaissances, promotion de l'actualité, affiches, radiateurs d'information, animations et événements.
• "L'apprentissage spatial"Les rappels répétés aident les gens à acquérir des réflexes.

Quelle que soit votre mise en œuvre de ces modèles, vous devrez trouver des occasions de mélanger les activités et de faire plusieurs choses en même temps, par exemple

• le codage et la documentation
• fournir (principalement avec un peu de code) une documentation testable
• tester à la fois le code et la documentation
• se mettre d'accord sur le contenu avec les parties prenantes
• partager le contenu avec les parties prenantes

Par exemple, l'approche de Sébastien Fauvel en matière de DL est une tentative de fusionner cette activité en utilisant des scripts de test pour générer une documentation lisible, la documentation est ensuite utilisée comme référence pour mettre en évidence les divergences avec les versions plus récentes [Fauvel 2020] [Fauvel 2022].

‍

En plus de ces modèles, vous devez également prêter attention à certains anti-modèles tels que :

• Le "dévouement humain" : le fait de consacrer des personnes spécifiques à la documentation permettra aux développeurs de se débarrasser de cette tâche.
• "Diagrammes polis" : les outils supportant des notations standard telles que UML ou BPMN amènent les gens à creuser leurs diagrammes plus profondément à mesure qu'ils découvrent les fonctionnalités de l'outil.
• "Connaissance redondante" : cela conduit au problème de l'obsolescence du contenu déprécié.

‍

De nombreux autres patterns et antipatterns peuvent être trouvés [Martraire 2019] et les connaître est la première étape pour éviter les pièges et essayer certaines pratiques pour commencer à innover dans la DL.

‍