Living documentation - tu ne sais pas encore mais tu l'as déjà documenté

Présentation par Marc Bouvier coach technique et co-organisateur du meetup Software Crafters Strasbourg.

Qu’est-ce que la documentation ?

Marc définit la documentation d’un produit informatique comme la connaissance partagée. Prenant l’exemple d’un consultant abordant un nouveau projet, il décrit les difficultés rencontrées pour accéder à une documentation utile. Les obstacles dans l’obtention des droits d’accès au repo, l’organisation du projet, la flakiness des tests, la dépendance à des outils tiers (suite Office) sont autant de facteurs agravants.

Que documenter ?

Pour Marc, l’effort de documentation doit porter sur les connaissances spécifiques, requises sur le long terme, ou par de nombreuses personnes. Il recommande de capitaliser sur la connaissance interne au produit : le code, les tests, les générateurs de documentation (JavaDoc, JSDoc, Doxygen…), les commentaires exécutables (pour Python, Elixir, Rust, ou Go), les manifestes, l’IaC, les pipelines, les logs et traces, l’outillage… pour aboutir à une documentation vivante, fiable, collaborative et pertinente.

Des idées pour augmenter la documentation

Marc nous livre une quantité d’idées pour améliorer notre documentation :

  • Réduire le bruit (enlever les redondances, travailler le nommage)
  • Partager un langage commun (ubiquitous language)
  • Penser BDD en utilisant ou non Cucumber ou SpecFlow
  • Utiliser les code snippets dans la JavaDoc, en Java 18
  • Développer des tests d’architecture avec ArchUnit
  • Alimenter un Word Cloud depuis le code (par exemple avec ce plugin Maven)
  • Annoter le code pour s’y référer plus tard (par ex : @GoodExample) ou générer un glossaire
  • Utiliser des générateurs de diagrammes (PlantUML, Mermaid, ditaa, Graphviz)
  • Utiliser des outils d’analyse statique de code (SonarLint, SonarQube, SonarCloud, ESLint, GitLab SAST analyzers…)
  • Implémenter une visite guidée du code (CodeTour ou Asciidoctor)
  • Développer des API REST avec des contrôles hypermédias
  • Mélanger le code et la documentation sous forme de notebooks (Jupyter, Livebook)
  • Concevoir un Design System
  • Ecrire ses présentations avec Asciidoctor reveal.js
  • Rédiger des messages de commit pour construire l’historique des intentions derrière les modifications (par ex. avec Conventional Commits) et traiter votre code comme une scène de crime
  • Écrire les README en Markdown (ou en AsciiDoc)
  • Mettre en place un parcours d’accueil comme décrit par Dan North
  • Rédiger des Architecture Decisions Records
  • Générer des rapports d’audit d’accessibilité avec FRAGO
  • Produire son propre technology radar
  • Convertir les fichiers Compose en représentation graphique (par ex. avec Graphviz)
  • Utiliser l’IDE pour générer les documentations techniques, diagrammes ad-hoc et graphes de dépendance
  • Commencer l’automatisation par la documentation des étapes nécessaires, puis en convertissant ces étapes en scripts appelés par un outil d’exécution de pipelines

L’importance des conversations entre humains

Au delà des outils, les conversations entre humains sont primordiales :

  • Avec le métier
  • Les revues de code
  • Le pair programming, le mob programming
  • Le 3 amigos

ROTI :

  • 3/5 : 1
  • 4/5 : 5
talk