Les bonnes pratiques autour de la documentation interne

0:14 Bonjour tout le monde, merci Noémie. Effectivement, je suis très contente d'animer ce meet-up autour de la documentation interne. C'est un sujet assez récurrent en entreprise. Et pour ce sujet, on va accueillir... Nous avons Maxime Thoonsen, qui est CTO chez Theodo. Arthur, Magne, CTO et cofondateur de Promyze, et Cyrille, Martraire, CTO et partenaire chez Arolla. J'invite Maxime à nous rejoindre sur scène. Hello tout le monde. Bonjour Maxime, chacun aura environ 15 minutes pour parler de la politique interne résolue. Et en parallèle, vous pouvez chatter dans la partie droite, dans la partie Q&A. Je pense qu'on... Si je vous fais une petite question rapide pendant que tu me parles. Maxime, je te laisse.

1:18 Yes. Vous voyez mes slides, c'est bon? Oui, c'est bon. Top. Du coup, bonjour à tous. Aujourd'hui, je vais vous parler de comment on... On organise la documentation interne chez Theodo avec Notion. Je vais d'abord faire un rapide historique pour savoir comment on en est arrivé à utiliser Notion, comment on l'utilise comme portail interne, puis un peu plus comment on l'utilise pour la documentation technique. Et après, je finirai sur nos apprentissages et les prochains challenges qu'on n'a pas encore craqué. Alors, l'historique. Quand je suis arrivé en 2013, on utilisait un simple wiki en PHP. Ça répondait à pas mal de besoins. Le gros point fort, c'est que c'était ultra rapide. Les pages chargeaient instantanément. Donc ça, c'est toujours hyper agréable. Les problèmes, c'était que ce n'était pas super beau, que la recherche ne marchait pas terrible et que la facilité de création de contenu, c'était moyen. Quand on voulait créer des bullet points, ça allait, mais dès que c'était des tableaux, des formes un peu plus complexes, c'était compliqué.

2:26 Du coup, rapidement, on a rajouté un WordPress. Donc là encore, c'était ultra rapide, c'était un peu plus beau et c'était un peu plus facile de créer du contenu. Mais le problème c'est que ça ne scale pas. A l'époque, l'arborescence c'était une home page avec une grande liste de... De sujets et la recherche c'était en gros un contrôle F sur la page. Donc c'était pas terrible et ça ne scellait pas des masses. C'est comme ça qu'on est arrivé à utiliser GitBook. Donc là c'était beaucoup mieux en termes de design. et de faciliter la création de contenu. C'était top. La recherche marchait aussi beaucoup mieux. Par contre, le gros problème qu'on a eu, c'est que notre façon d'utiliser et le nombre qu'on était, environ 200-300, faisait que le guidebook était très lent à afficher les pages. Et on a cherché une autre solution et il y a des gens qui ont testé en parallèle Notion et c'est comme ça qu'on utilise aujourd'hui Notion.

3:28 Notion, si je compare aux autres solutions, ce qui est top c'est que ça permet de créer du contenu hyper facilement, c'est assez joli. Ce qui est un point important, j'en reparlerai après. La recherche marche plutôt pas mal et c'est plus rapide, mais on ne retrouve pas encore la rapidité d'un WordPress ou d'un Wikipédia qui affichait en moins de 500 millisecondes n'importe quelle page. Le premier apprentissage que je voulais vous partager, c'est qu'on savait qu'on allait perdre la connaissance en faisant des migrations de WordPress à Gitbook, de Gitbook à Notion. Mais même en le sachant et en faisant attention, on en a perdu énormément. Donc, il faut vraiment, quand vous faites une migration, dites-vous, il faut vraiment prendre ce sujet au sérieux parce que vous allez perdre beaucoup de connaissances. Du coup, on a fini la grande migration de Gitbook vers Notion et quelques temps après, il y a eu une histoire avec un pangolin.

4:30 Colin, que vous connaissez tous, qui nous a forcé à migrer également tout notre management visuel vers Notion. Il faut savoir que nous, à Theodo, on utilisait beaucoup, beaucoup les objets physiques. On aimait bien... Donc ça, c'était une photo d'un scrum board. On utilisait des post-it, tout ça. On avait aussi beaucoup de management sur les murs. Et du coup, au moment du premier confinement, on s'est retrouvé bloqué. Et on a tout migré sur Notion. C'est comme ça que Notion est devenu beaucoup plus qu'un... L'outil pour la doc interne, c'est vraiment devenu un portail interne complet. Par exemple, ça c'est notre home page de notre notion, où on a une arborescence assez flat au début pour que tout le monde puisse trouver des sujets. Notre théorie, c'est que via la recherche notion, les gens vont pouvoir trouver ce qu'ils connaissent déjà, mais par contre, ils ne vont pas trouver ce qu'ils ne connaissent pas.

5:30 Et c'est le rôle d'avoir une bonne arborescence via un peu classique. C'est que ça permet aux gens de se balader dans le notion et de trouver des sujets, de trouver des réponses à des questions qui... qu'ils n'avaient pas pensé. Ils découvrent, ça permet aux gens de découvrir un petit peu des nouveaux sujets quand ils sont créés. Ce qui est génial pour l'onboarding des nouveaux, parce qu'on ne peut pas tout leur raconter en 10 minutes, donc du coup, ça leur permet de découvrir un peu plus la boîte comme ça. Il y a combien de personnes qui utilisent Notion aujourd'hui? Toute la boîte utilise Notion tous les jours et aujourd'hui on est 160. Et le groupe Théodo, on est un peu plus de 500 et c'est pareil, tout le monde l'utilise tous les jours. Merci, c'est agréable pour la question de Cyril. Okay. Top, top. Et il faut savoir qu'on a un notion partagée pour tout le groupe, ce qui permet aussi pas mal de collaborations. Entre les startups.

6:33 Pour vous expliquer un peu plus ce qui se passe au cœur de la machine de notion, il y a un concept qui est assez important, qui est le concept de base de données. Grosso modo, c'est des tableaux dynamiques sur lesquels on peut rajouter des propriétés. Et ce qui est cool, c'est qu'on peut rajouter des filtres, faire des tris ou faire des relations entre les tableaux. Et donc du coup, rien qu'avec ces trois features, on peut créer des vues personnalisées assez puissantes. Je vais vous montrer quelques exemples. Par exemple, on a un tableau avec toute la liste des personnes à Theodo et on a pu rajouter des informations pour chacune. Donc, n'importe qui peut avoir accès à cette page et voit, ah bah tiens, Maxime, il est arrivé à telle date, il est tel niveau, il a tel rôle dans l'entreprise, il a telle relation management avec ces autres personnes et quelques autres informations, ce qui permet à tout le monde de comprendre plus facilement la boîte, surtout quand on arrive et qu'on ne connaît pas encore tout le monde.

7:38 L'idée, c'est de créer des vues qui vont faciliter la coopération entre toutes les personnes de l'entreprise. Un autre exemple, c'est qu'on est une boîte de services, on crée des projets pour nos clients. Et un moment très important dans la... C'est le début du projet, c'est là où il y a potentiellement beaucoup de problèmes. Et grâce à Notion, je me suis fait, en tant que CTO, une petite vue sur tous les nouveaux projets qui démarrent. Et avec une équipe dédiée à ça, on s'assure que les projets démarrent dans de bonnes conditions. Et un truc cool qu'on a fait, c'est que cette information, on l'a appelée la tour de contrôle, on l'affiche dans l'entrée, en physique, sur un écran, ce qui permet aux gens de regarder quand ils passent et de voir s'ils peuvent potentiellement aider les projets. Il y a deux, trois autres vues comme ça, de notions qu'on partage à certains endroits de l'entreprise.

8:44 Et l'idée, c'est que ça nous permet de briser les silos et de permettre aux gens de Thodo de coopérer en regardant quand ils peuvent aider une autre équipe en voyant ces informations-là. Pour les équipes produits, un exemple d'utilisation de Notion, c'est de créer un dashboard où, en un coup d'œil, ils peuvent voir où en sont le projet. Ça, ça sert pas mal pour les équipes projet et aussi pour leurs managers qui, comme ça, en un coup d'œil, ils peuvent voir la situation. Ah tiens, sur le produit, on en est là. Sur la qualité du code, on en est là. Sur le delivery, on en est là. Et du coup, rapidement, ils peuvent aider les équipes sur leurs problèmes. Et donc du coup, c'est assez efficace. Un autre bon point de notion, c'est que c'est assez facile de créer des pages publiques. Donc là, c'est notre Tribe Product qui a, la semaine dernière, créé une page notion publique avec toute la connaissance, enfin une partie de la connaissance qu'on a.

9:54 Sur le produit et du coup après ils ont fait un post LinkedIn et c'était bon ils avaient leur leur documentation publique accessible à tous. Et l'équipe recrutement a fait également la même chose, une page notion avec toutes les offres d'emploi. Et maintenant, quand on va sur le site Theodo et qu'on clique sur offre d'emploi, on arrive sur cette page notion. Et je sais qu'il y a beaucoup de... J'ai vu beaucoup d'autres entreprises le faire, parce que c'est vraiment hyper pratique. Si je fais un petit focus sur la documentation technique, on l'a organisé autour de la qualité et on a une grosse homepage avec toute une liste de thématiques et après dans chaque thématique, une liste de gestes. Donc ça c'est un bout de la home page de la tech qui est orientée qualité. Donc on voit qu'on a potentiellement beaucoup de sujets, ça va de la CI à la code quality en passant par l'accessibilité.

11:00 Et donc on retrouve un peu le même esprit que à l'entrée d'une notion, c'est que ça permet aux techs de chez nous d'aller un peu regarder, découvrir des nouveaux sujets en partant de ces homepages. Et ensuite, quand ils veulent creuser, par exemple, la qualité du code, ils arrivent sur une autre sous-homepage avec toute une liste de ce qu'on appelle nous les standards, qui sont les comment faire un bon geste. Et pareil, ils peuvent creuser. Par exemple, si je prends le premier, faire une bonne pull request. Ils tombent sur une page avec les points de contrôle qui leur permettent de s'auto-évaluer tout seul sur le geste qu'ils ont fait. Et s'ils ne l'ont pas encore fait, ou qu'ils veulent approfondir un peu pour être sûr de bien faire le geste, une liste d'étapes de comment faire une bonne pull request. Et enfin, au niveau de ces standards, il y a potentiellement, pas pour tous, mais pour ceux où on a fait le travail, il y a un lien vers une formation qu'ils peuvent suivre pour être sûrs d'être formés.

12:12 Et ce qui est cool, comme je vous l'expliquais avec l'histoire des tableaux, c'est qu'on peut faire des relations. On peut aussi créer une vue, enfin on a créé une vue avec toutes les formations de Theodo. Et donc du coup... Quelqu'un à Théodo qui veut trouver une formation, il a plusieurs moyens de la trouver. Il va avoir la recherche, l'arborescence par les standards et l'arborescence par le catalogue de formation. Ce qui permet de rendre accessible encore plus les formations et l'information. Un autre exemple, c'est par exemple pour la thématique performance, on a un tableau avec tous les outils qui peuvent aider à résoudre des problèmes. Et pareil, ces outils, on les retrouve dans des formations ou dans des standards. L'information, elle est croisée. Et ensuite, on arrive sur une seule page qui permet d'expliquer comment utiliser ces outils. Alors, nos apprentissages et les prochains challenges. Ce qui a vraiment bien marché pour la migration vers Notion, c'est que Julien, le CEO, s'est énormément impliqué et a vraiment été un peu l'architecte de ce Notion.

13:28 Et en fait, pourquoi je pense que c'est important, c'est qu'après, il faut motiver tout le monde à mettre leur savoir au bon endroit dans Notion pour le partager. Et s'il n'y a pas un leadership fort, potentiellement, ça ne va pas marcher. Je vous en ai parlé, je pense qu'il ne faut vraiment pas sous-estimer l'importance de faire du beau. La documentation, les gens, des fois, rechignent à aller la regarder ou à en créer. Et si c'est beau, ce qu'on a remarqué, c'est que les gens sont beaucoup plus enclins à le faire. C'était une des grosses valeurs de Notion, c'est que c'est facile de faire des trucs assez jolis. Et du coup, les gens sont vraiment motivés à utiliser l'outil. Et sans être caricatural, souvent les techs, on n'est pas les plus forts pour faire du beau, mais donc du coup, ne sous-estimez pas ce point-là. L'architecture, on a essayé plusieurs trucs et c'est normal de passer du temps. Notre théorie, c'est qu'il faut une architecture qui permette de retrouver rapidement de l'information, tout en laissant une liberté.

14:30 de contribution, il ne faut pas que ce soit trop rigide, sinon ça va trop contraindre les gens et ils vont moins avoir envie de contribuer. Il faut que votre architecture permette de faire un joli bordel organisé, si je puis dire. Et enfin, encourager les initiatives, vous n'allez pas faire une architecture bonne du premier coup, Et une bonne idée qui est sortie comme ça, c'est les pages Everything About, qui... En gros, ce sont une autre manière de recenser l'information dans le CION. Et petit à petit, elles sont un peu apparues un peu partout. Et maintenant, ça aide encore plus à retrouver l'information. Les prochains défis, avoir un système de maintenance pour que nos informations soient à jour. Là, vous avez un petit coup d'œil à notre DSI qui est super bien rangé. Je n'ai pas encore de système pour que l'information soit à jour tout le temps.

15:31 S'il y en a qui ont trouvé, je suis preneur de conseils. Et sinon, en regardant un peu plus finement comment les gens utilisent la doc aujourd'hui, on s'est rendu compte que majoritairement, à part quand les gens viennent d'arriver à Theodo, mais les développeurs un peu expérimentés, ce qui se passe, c'est qu'ils vont coder et quand ils sont face au problème, ils vont aller chercher dans le lotion comment résoudre leur problème. Ce que j'aimerais bien arriver à faire, c'est que les gens aillent voir au moment de coder la doc qui leur permet de faire bien du premier coup, pour éviter de faire des erreurs. On a quelques expériences en cours, mais pour l'instant, on n'y arrive pas du tout. Et ça va être un des points du talk prochain. Donc ça va être cool. Voilà, merci. Et puis je répondrai. Aux questions tout à l'heure s'il y en a.

16:33 Merci à tous. Merci Maxime. Peut-être qu'on peut répondre rapidement de Stan et ensuite on pourra prendre deux questions à la fin du meet-up. De toute cette organisation justement, et comment ça ne soit pas trop bizarre. Donc, tu commences un petit peu à y répondre. Oui, alors il n'y a pas un système très clair. Ce qui s'est passé, le gros de l'effort, ça a été vraiment au début, de définir une architecture où les gens s'y retrouvent. Et en ce moment, ça va être un petit peu... Par exemple, on a quelqu'un qui est honneur de tout ce qui est performance à Théodo, il va s'assurer que sa partie de notion soit à jour. Ça marche un peu comme ça. Il n'y a pas quelqu'un qui a la casquette, je m'assure que la doc soit super, que la notion soit super propre partout. Et quand il y a des grosses décisions à prendre, on en parle un peu collégialement, et Julien

17:39 et Jason, parce qu'ils étaient deux à créer l'architecture au début, généralement c'est eux qui vont un peu trancher en discutant avec tout le monde. Mais il n'y a pas quelqu'un qui est tout le temps proactivement en train de traiter. Merci Maxime. Je vais donner la parole à Arthur maintenant. Tu pourras revenir en fin de... Yes, à tout à l'heure. Arthur, qui est pour notre de Promyze. Et puis, n'hésitez pas à poser vos questions dans la... Merci Céline. Alors ce qui est intéressant, c'est que justement, j'ai pu regarder quelques questions dans la partie Q&A et je vais essayer de répondre, peut-être en présentant un petit peu ce qu'on a fait. Il y a une partie de la réponse à certaines questions qui va peut-être apparaître. Je vais partager mon écran, normalement ça devrait marcher directement. Parfait. J'ai un seul slide, donc ça ne sera pas trop long.

18:39 Je vais lancer mon chrono pour ne pas exploser le temps. La première chose que je voudrais expliquer, c'est que cette problématique de diffusion des connaissances au niveau des équipes techniques et au niveau des entreprises, c'est une problématique qui grandit de plus en plus. On le voit dans l'ensemble des DSI, que ce soit des startups d'ailleurs, des PME ou des grands comptes, parce qu'aujourd'hui, il y a une vraie problématique de turnover dans les équipes de développement. Vous l'avez sûrement vu dans vos entreprises. Il y a aussi des problématiques d'offshore, des problématiques avec le remote, l'évolution des technologies qui changent tout le temps, des nouvelles manières de faire également, que ce soit en termes d'architecture, de sécurité, de performance, de clean code, de test, etc. En fait, tout ça, ça fait qu'aujourd'hui, Une personne isolée dans l'entreprise ne peut pas acquérir toutes les connaissances dont elle a besoin pour travailler de manière autonome, que ce soit en se formant, que ce soit en lisant même tout seul de la doc, etc. Aujourd'hui, ce n'est plus possible. Et une des manières de répondre à ce problème, ça va être d'instaurer justement une culture de l'apprentissage au sein de l'entreprise.

19:44 Donc ça, c'est une des capacités qui est poussée par l'étude Accelerate, faite par le laboratoire d'Aura. On n'aura pas le temps d'en parler aujourd'hui, mais il y a beaucoup de capacités qui sont poussées justement par cette étude Accelerate qui vont dans cette direction de créer une culture d'apprentissage. Et l'objectif de ça, c'est de passer par l'intelligence collective au sein des équipes. Donc en gros, chaque personne va avoir son domaine d'expertise, ses connaissances qui vont être propres en fonction de l'expérience que la personne a acquérie, de la formation qu'elle a fait et de plein de choses. Et l'objectif, c'est de faire en sorte qu'il n'y ait pas un phénomène de héros dans les entreprises où une personne centralise toute sa connaissance. Parce que si jamais cette personne part ou que cette personne attrape le Covid, ce qui peut arriver assez souvent en ce moment, il ne faudrait pas que le reste de l'équipe soit complètement bloqué et doivent se reformer et réapprendre un petit peu tout ce que cette personne avait mis du temps à apprendre. Donc pour ça, l'objectif, ça va être de donner des outils pour l'équipe pour qu'elle puisse être capable de partager cette connaissance, qu'on soit capable de capitaliser vraiment sur l'expertise et les connaissances de tout le monde.

20:50 Mais il ne suffit pas de donner des outils, il faut aussi mettre en place une méthode, un process qui permet justement, alors là c'est pour répondre à une question qui a été posée, qui est comment est-ce qu'on fait pour maintenir cette doc à jour, comment on fait pour s'assurer que tout le monde est d'accord et que c'est la bonne manière de faire et que ce soit vraiment fait de manière collaborative. Pour ça, pour moi, un outil ne suffit pas, il faut mettre en place aussi des méthodes. Alors on a essayé. De mettre en place pas mal de choses chez Promyze avec différentes DSI, différentes entreprises. Et un format sur lequel on est tombé, qui fonctionne très bien maintenant depuis à peu près deux ans, qu'on a mis en place avec pas mal d'entreprises, c'est un format qu'on a appelé des ateliers craft. Donc là, je vais vous présenter un petit peu. Comment ça fonctionne ? L'objectif, c'est que toutes les personnes de l'entreprise qui font de la technique, donc là, par rapport à Maxime, je recentre un petit peu sur la partie connaissance technique en termes de pratique, d'architecture, de clean code, de sécurité, de performance, de React, de Java, de gestion d'erreurs, etc. Donc tout ce qui va toucher vraiment à du code source, tout ce qui va évoluer très rapidement et qu'on ne va pas pouvoir retrouver dans Notion ou des outils comme Confluence ou des Wikis, parce que justement c'est quelque chose qui évolue trop vite

22:00 et on a besoin de supports de code source récents aussi pour illustrer un petit peu ces pratiques. Et là, des outils comme Notion ne sont plus adaptés. Mais c'est très complémentaire parce que dans Notion, on va retrouver tout ce qu'a présenté justement Maxime. Donc vraiment, les deux approches sont complémentaires. Et l'objectif, ça va être que tout le monde puisse participer, c'est-à-dire qu'on soit stagiaire, alternant ou tech lead, tout le monde va pouvoir identifier ce qu'on va appeler des bonnes et des mauvaises pratiques de développement ou de test directement dans le code source de notre projet. Pour ça, je vous montrerai, mais en fait, il faut que ce soit intégré dans l'environnement des développeurs. Non, les gens vont... La première version qu'on avait, on n'avait pas d'extension et de plugin, et en fait, les gens avaient du mal à sortir de leur environnement, les développeurs et développeuses, et d'aller dans un nouvel outil pour renseigner de la documentation. C'est quelque chose où on a vraiment du mal à prendre sur Ftext. C'est vraiment important que ce soit intégré dans l'environnement. Et l'environnement des développeurs, c'est quoi? C'est soit j'écris du code, je suis dans mon IDE, soit je suis en train de relire du code et je suis dans un outil comme GitLab ou... GitHub ou Azure DevOps ou Bitbucket, et là je fais une rélecture de code.

23:03 Donc première chose, tout le monde peut identifier ce qu'il trouve pertinent dans le code en termes de bonne ou de mauvaise pratique. Ensuite, de manière cyclique, c'est-à-dire une fois par sprint en général, ou une fois par semaine, ça va dépendre des organisations, on va se réunir pendant une heure lors de ce qu'on a appelé un atelier craft, en référence au software craftmanship. Mais l'objectif, c'est de se réunir pendant une heure et de passer en revue tout ce qui a été identifié par notre équipe ou notre communauté de pratique, en termes de bonne ou de mauvaise pratique, justement. Pour pouvoir valider en équipe que c'est vraiment la bonne manière de faire ou pas, et pour pouvoir transmettre justement ces connaissances. Un point important également, c'est que pendant cet atelier craft, chaque personne qui a identifié une pratique va l'expliquer aux autres. Et sur l'approche pédagogique, le fait d'expliquer quelque chose qu'on a identifié, on a tout de suite tendance à vachement mieux le comprendre et l'apprendre, parce que ça nous force à être pédagogue et expliquer vraiment avec du recul pourquoi est-ce que c'est la bonne manière de faire. Donc on se pose des questions qu'on ne se posait pas forcément avant. Ensuite, tout ça, on va aboutir à un référentiel. Par contre, si on s'arrête là, et c'est ce que disait Maxime, il va y avoir un souci, parce qu'on va se transformer en

24:09 un outil où justement il y aura de la documentation, mais personne ne va la lire, parce que les développeurs en ont besoin quand ils sont en train de développer, quand ils sont en train de faire une fonctionnalité au droit de l'ordre du code. Et on n'a pas le réflexe d'aller regarder. Ah oui, est-ce qu'il y a des mises à jour, etc. Évidemment, c'est compliqué. Donc pour ça, toujours pareil, par la suite, on a eu pas mal de retours d'expérience où des gens nous ont dit, en fait, Il faudrait pousser ces bonnes pratiques, cette documentation, cette connaissance aux développeurs et aux développeuses au moment où ils en ont le plus besoin, c'est-à-dire pendant qu'ils sont en train de faire une fonctionnalité. Et donc là, toujours pareil, on s'est servi des extensions qu'on avait déjà créées pour, par similarité, être capable de pousser justement des pratiques. Je vais vous montrer un exemple concret d'utilisation pour que ce soit vraiment plus simple. Mais l'idée, c'est vraiment de se concentrer sur cette documentation vraiment très technique, très liée au code. Donc là, je suis dans mon IDE, je suis dans VS Code. C'est pareil sur les autres IDE. Donc tout ce que j'ai à faire, c'est d'installer l'extension qu'on a qui s'appelle Promyze. En fait, cette extension, elle va nous permettre d'une part de...

25:09 Toutes nos bonnes pratiques, qu'on va regrouper dans ce qu'on appelle nous des catalogues de bonnes pratiques. On va les regrouper par thématique en fait, on aura des pratiques par exemple sur du BDD, des pratiques d'architecture hexagonale, des pratiques liées au référentiel de WASP, sur des pratiques de sécurité, etc. Donc tout ça, ça va être des pratiques qui vont être créées directement par nos équipes en interne. En fait, on aime bien arriver avec cette approche cookie-vid, c'est un peu comme Notion d'ailleurs, où c'est l'équipe elle-même et les équipes d'entreprise qui vont créer leur propre documentation, leur propre bonne pratique. Pourquoi? Parce qu'on s'est rendu compte qu'en fonction des contextes, qu'on soit chez ManoMano ou chez Ubisoft ou dans une SN, on ne va pas avoir les mêmes problématiques, que ce soit en termes de sécurité, de performance, de manière de développer et même d'expérience des personnes. Donc c'est important que chaque entreprise et chaque équipe puisse avoir son propre référentiel de bonne pratique, sa propre manière de développer. Et donc, tout ça, on va le retrouver ici. Mais surtout, ce qui va être utile, c'est que lorsque je suis dans mon IDE, je vais pouvoir identifier personnellement ce que je trouve être une bonne ou une mauvaise pratique.

26:11 Donc, je peux mettre en avant des choses bien. Mais par exemple, dans cet exemple, là, c'était sur du vieux code à nous, il y a un problème de performance, en fait, ici, qui avait été remonté par un client. Et c'est quelque chose qui, personnellement, m'a sauté aux yeux parce que je fais du JavaScript depuis un petit moment. Et j'ai vu qu'il y avait un await dans la boucle for, ce qui vient bloquer les itérations et ça rend les appels. séquentiel alors qu'ici on aurait pu les faire en parallèle. Donc personnellement ça m'a sauté aux yeux. Par contre la personne qui avait écrit ça ne savait pas et en fait quand on fait des ateliers comme ça avec pas mal d'entreprises, la plupart des développeurs qui font le JavaScript ne sont pas au courant que le await vient bloquer la boucle fort. C'est un exemple parmi tant d'autres mais celui-là il est assez parlant. Donc là ce que je peux faire c'est sélectionner ce code là, faire un clic droit et j'ai une option Promyze qui me permet d'identifier une nouvelle pratique. Donc en fait je vais créer de la documentation, je vais créer de la connaissance. Je vais l'appeler use promise. hotall.parallèles.codes. On aurait dû utiliser promise.all pour faire des appels en parallèle. Je vais l'arranger dans mon équipe, ma future team que j'appelle Marketplace Web, mais on a aussi la possibilité de créer ce qu'on appelle des communautés de pratiques ou des guides de pratiques.

27:16 C'est vraiment assez important de casser des silos par projet dans les entreprises et plutôt regrouper des personnes par thématique, par technologie utilisée. C'est super important justement en termes de transfert de connaissances et d'intelligence collective. Je vais l'arranger dans ma future team Marketplace Web. Je veux dire que c'est une pratique de performance et c'est du JS. Une fois que j'ai identifié cette pratique, la pratique est créée. Je vais corriger ce code là parce que je vais faire mon petit refactoring pour corriger ça. Une fois que j'ai fait la correction, je vais pouvoir envoyer le refactoring que j'ai fait comme étant la correction du problème que j'ai identifié avant. Donc ça, c'est la manière principale d'identifier la pratique, c'est depuis mon IDE. En fait, ça ne me ralentit pas dans mon process, mais je vais pouvoir en discuter avec toute l'équipe à la fin du sprint. C'est ça qui est important, c'est ce moment d'échange. De la même manière, je peux le faire depuis GitLab, par exemple. Je suis en train de faire une revue de code et je vois ici qu'il y a quelqu'un qui a manipulé des dates avec Moment.js, sans gérer les time zones, en faisant un truc bizarre avec du charade zéro, etc. C'est bizarre, mais ça va fonctionner ici.

28:17 Par contre, je me dis personnellement, ça serait intéressant de sortir un service qui va permettre de gérer justement la manipulation des dates plutôt que de le faire dans un composant, parce qu'ici je vais avoir du code dupliqué partout, ça ne va pas être maintenable, etc. Donc là, je pourrais mettre un commentaire dans la pull request, mais je vais faire du feedback qu'il y a une seule personne et le commentaire va être perdu lorsque le code va être mergé. Donc, je ne vais pas capitaliser sur tout ça. Donc là, ce que je peux faire, c'est sélectionner ce morceau de code, faire un clic droit, et toujours pareil, en fait, avec les extensions, je vais pouvoir créer une pratique ici. Je me mets dans mon équipe Marketplace Web, je cherche une pratique que j'appellerai Yules, date, formateur service to manipulate date, vous avez compris. Je vais créer cette pratique parce qu'elle n'existe pas encore, je vais pouvoir lui mettre une description, etc. Et d'ailleurs, en retour d'expérience, souvent dans la description, on retrouve des liens vers de la documentation qui peut se retrouver dans nos chaînes, par exemple, qui serait une documentation vachement plus détaillée sur justement toute la... Donc il y a des liens qui peuvent être faits entre ce qu'on va retrouver dans Promyze et des outils de la doc classique.

29:19 D'ailleurs, je vais dire toujours pareil, est-ce que c'est un exemple positif ou négatif? Dans mon cas, c'est un exemple négatif, parce qu'évidemment, ce n'est pas fait. Et ce qui va se passer, c'est qu'à la fin du sprint, on va se réunir avec toute mon équipe. sur l'interface web, en fait, les cerquessades, l'interface web, c'est vraiment juste un support aux ateliers craft. Donc vraiment tout ce qui est intégré dans notre plateforme, c'est un support à ce format d'atelier craft. Donc évidemment, ça ne peut pas marcher si vous ne mettez pas en place ensemble ce format d'atelier craft. Et là, chaque personne va pouvoir présenter la pratique. Je vais montrer la correction que j'ai proposée. Quelqu'un va me dire, ce que tu as écrit, c'est cool, mais en fait, tu aurais pu enlever tout ce code-là qui ne sert à rien. C'est quelqu'un qui me l'a dit il n'y a pas longtemps. On peut l'écrire de cette manière-là, ça va être pareil et c'est vachement plus lisible. Je vais dire OK, c'est cool, donc on va enregistrer cette correction. Je vais valider la pratique en équipe parce qu'on va se dire qu'on est tous d'accord. Mais si jamais quelqu'un n'est pas d'accord, je peux lancer ce qu'on appelle une battle sur la pratique. Et à ce moment-là, pendant le sprint suivant, n'importe quelle personne de l'équipe peut aller voter. Donc, on retrouve la pratique avec les exemples positifs, négatifs, etc.

30:22 Et on va pouvoir voter en disant est-ce que je suis plutôt pour ou contre. Et surtout, ce qui est important, c'est qu'on va mettre des arguments. Quand est-ce qu'il faut appliquer ça? Quand est-ce qu'il ne faut pas l'appliquer? Parce qu'aussi, une problématique qu'on va avoir, qui d'ailleurs n'est pas vraiment une problématique, c'est que ces différentes pratiques qu'on va avoir, elles ne vont pas être toujours applicables ou non. Ce ne sont pas des pratiques qu'il faut toujours appliquer. Et c'est important justement de laisser le choix à la personne de« est-ce qu'il faut l'appliquer ou non? » mais il faut juste que la personne soit consciente de« pourquoi est-ce qu'il faut l'appliquer ou pas? »« Dans quel cas il faut l'appliquer ou pas? » Une fois que je vais valider ces différentes pratiques, je vais les faire pousser de là, Là, il y a un point important qui avait été remonté par Maxime, qui est que si quelqu'un dans son IDE est en train de développer et d'écrire du code comme ça, avec ma boucle fort, je vais avoir des pratiques qui vont être suggérées automatiquement. Donc, on ne va pas pousser le référentiel entier, parce que ça, c'est ce qu'on avait avant, mais évidemment, les gens ne vont pas le voir. Il y a beaucoup trop de choses. Par contre, ici, dans tout le référentiel, on ne va prendre que trois pratiques. On va dire, là, ce que tu es en train d'écrire, ça ressemble beaucoup à cette pratique-là.

31:23 En fait, tu devrais peut-être utiliser Promyze.old parce que ton appel est peut-être justement un appel qui pourrait être fait en parallèle. On ne vient pas bloquer la chaîne. Et si je suis conscient qu'on appelle et pas un appel parallèle, je ne suis pas obligé de faire. Mais par contre, ce qui est important, c'est de pousser ces connaissances au bon moment. On va dire attention, là, il y a un await, mais il n'y a pas de try-catch. Là, il y a vraiment un bug potentiel. En fait, normalement, il faut un try-catch pour nous autour des appels HTTP. Donc, si jamais je me mets sur la ligne 68 ici, vous voyez, j'ai la même pratique sur un HTTP code ou un try-catch, mais en positif cette fois, parce que là, c'est une bonne manière de faire. Et ça, ça va marcher évidemment pour n'importe quel type de langage, donc sur des pratiques de test, de CSS, de HTML, etc. Et on va avoir la même chose en fait pour les revues de code. Et là, l'idée est toujours pareille, c'est de ne pas bloquer les revues de code. Ce n'est jamais très bon de bloquer automatiquement les choses. Mais on va plutôt... Apporter un assistant à la personne qui fait la revue de code en lui suggérant des pratiques, en lui disant, tiens, attention, si tu scrolles, par exemple, à ce niveau-là, là où on a identifié ensemble une pratique tout à l'heure, je vais voir cette pratique qui va être suggérée. Use that formatter service to manipulate date.

32:25 Et le but, là, c'est de ne pas oublier des pratiques et d'essayer de partager ces pratiques entre les différentes équipes. Et une manière de faire également, donc là c'est l'étape d'après si jamais vous avez beaucoup d'équipes dans l'entreprise, c'est de pouvoir récupérer les pratiques qui viendraient d'autres équipes d'entreprise. Donc pour ça, on a une partie qui permet de revoir les pratiques créées par les autres équipes. Donc là, je vais dire, je ne m'abonne pas à AngularJS parce qu'AngularJS, je n'en fais plus depuis des années. Je vais m'abonner par exemple à du Java parce que je fais du Java, etc. Et derrière, je vais regarder toutes les pratiques créées par les autres équipes. Et à chaque fois, je vais pouvoir soit récupérer la pratique si elle m'intéresse, par exemple, Celle-là, use the timer to avoid too many HTTP calls. Vous voyez, ce n'est pas uniquement des bonnes et des mauvaises pratiques en termes de qualité de code, mais ça va être aussi des connaissances d'ingénierie ou des connaissances sur des manières d'appliquer des choses en React, d'instancier des moteurs de jeu, par exemple, c'est ce qu'ils font chez Ubisoft et des trucs comme ça. Ça va vraiment être différent en fonction du contexte des différentes équipes. Et derrière, je vais pouvoir récupérer la pratique si elle m'intéresse. Ou alors mettre un commentaire à l'équipe qui a créé cette pratique-là pour lui dire, attention, par exemple, tu utilises Moment.js qui est déprécié depuis deux ans, utilise plutôt DateFNS qui est vachement QDG et qui gère les time zones directement, etc.

33:34 Donc vraiment l'objectif de tout ça, ça va être de créer cette notion de communauté un petit peu entre les équipes pour être capable d'uniformiser un petit peu nos pratiques et de diffuser nos connaissances. J'ai terminé au niveau du timing, ça va faire la bonne transition avec Cyril qui va nous montrer directement comment est-ce qu'on peut intégrer des choses directement dans le code source pour apporter plus d'expression directement dans le code source. Je ne sais pas Céline si on a le temps peut-être pour une question maintenant ou si on voit ça après, c'est toi qui me dis. Alors, je ne sais pas beaucoup pour ta présentation et pour les démos de Promyze. Moi, j'ai une question, c'est moi qui l'ai posée personnellement. Je me demandais s'il y avait un plugin qui était prévu pour d'autres IDE comme Rider. Alors oui, ça fonctionne sur toute la suite JetBrains, donc Rider, IntelliJ, etc. Ça fonctionne sur Eclipse, sur VS Code et Visual Studio. Et... Et les outils de revue de code, c'est GitHub, GitLab, Bitbucket et Azure DevOps.

34:35 On a eu beaucoup de demandes d'équipes qui nous disaient que c'est dommage que la moitié de l'équipe est sur Eclipse. Ce serait bien qu'ils puissent participer aussi. Donc effectivement, normalement, à peu près tous les idées sont couvertes. Il n'y a que tout ce qui est iOS aujourd'hui qui n'est pas encore couvert parce que c'est un peu plus compliqué d'étoffer des petits guides là-dessus. Mais effectivement, oui. Très bien, on se garde d'autres questions pour la fin. Bonne transition pour Cyrille qui peut nous rejoindre sur scène. Parfait. Donc Cyril, toi, tu es chez Arolla et tu as même écrit un livre, Living Documentation. Et tu vas pouvoir nous dire... Je ne sais pas si c'est basé que sur ton expérience ou sur ce que tu as vu dans d'autres sociétés, mais je pense qu'on a beaucoup de choses à apprendre de ta présentation. Alors là, cette petite réponse, bonjour à toutes et à tous. Donc, effectivement, ce livre provient de dix années de réflexion entre globalement 2005 et 2015.

35:37 Le livre est sorti en 2019 chez Addison Wesley. Mais avant de parler de ce livre, j'aimerais bien vous parler d'une autre passion à moi, les termites. Est-ce que les termites font des plans quand elles construisent leurs nids qui sont aussi impressionnants? Certains peuvent faire 3 mètres de haut, ils peuvent être plus grands que des girafes. Alors bien sûr, c'est une question, la réponse, vous la connaissez, la réponse c'est non, bien sûr, les termites ne font pas de plan, c'est nous qui faisons des plans. Après, pour essayer de comprendre comment marchent ces merveilles d'ingénierie que sont les termitières. Vous savez que ces termitières sont des merveilles d'ingénierie. Elles sont des constructions éco-passives avec de la régulation de température, une ventilation contrôlée, des circulations, des défenses contre les intrus, etc. C'est des superbes, c'est des chefs-d'oeuvre. C'est des chefs-d'oeuvre et pourtant, les termites ne font pas de plantes pour construire ces chefs-d'oeuvre alors qu'elles les construisent de façon à grandir. En échelle, même par rapport à des aventures humaines, on est sur des grosses aventures. On est sur des milliers d'agents, des milliers de collègues qui travaillent sur un truc énorme.

36:41 Alors, comment ça se passe? Comment les termites coordonnent leur travail? Comment elles font leur plan? En fait, le plan, c'est le travail lui-même. Les termites, c'est un phénomène qui s'appelle la stigmergie en biologie. Et la stigmergie, c'est ce phénomène de collaborer au travers du travail lui-même. La termitière en cours de construction est son propre plan. Ça marche déjà pas mal, mais il y a un truc en plus. C'est qu'en plus, la termitière, les termites laissent des marques chimiques, des marqueurs, des phéromones pour être précis, aux endroits où elle passe le plus, ce qui en plus va encore plus améliorer, catalyser, ça va aider la collaboration à être encore plus efficace. Par exemple, où est-ce que ça se passe en ce moment? Où est-ce qu'il y a besoin de construire plus? C'est plutôt là que c'est chaud, c'est là où on y va, c'est là où les plus de termites vont aller. Alors, je ne sais pas vous, mais c'était une énorme inspiration, autant tout le travail sur le Living Documentation, parce que quand même, c'est assez fréquent qu'on observe que le travail au quotidien, à défaut de mieux, on pourrait dire, ça se passe de la même façon. On travaille énormément au travers du travail lui-même.

37:43 Le travail lui-même sert de son propre plan aussi. Et c'est quoi le travail? C'est des conversations qu'on a entre nous pour résoudre plein de problèmes, pour découvrir de la connaissance, et bien sûr, c'est aussi le code. Et je pense que ça vous paraîtra assez naturel d'admettre qu'assez souvent, On découvre ce qu'il faut faire en lisant le code. Et souvent, on s'en plaint. Est-ce qu'on a raison de s'en plaindre ou est-ce qu'au contraire, on devrait accepter ça et décider de le faire mieux? C'est cette deuxième option qu'on va étudier ensemble au travers de ce sujet de living documentation. Comment faire ça? Comment accepter que c'est un état normal de fait et qu'on peut faire des chefs-d'oeuvre avec et le faire bien? Je m'appelle Cyril Martraire, je suis cofondateur d'Arolla depuis 12 ans. On est tous chez Arolla avec mes 90 collègues, on est fan de toutes les choses, toutes les choses en DD, et aussi comment crafter l'architecture et comment faire tout ça d'une façon qui soit aussi à la fois professionnelle, qui marche bien et qui soit fun. Et donc, un peu plus de dix ans de réfléchir à ce sujet de la doc au travers de plein d'entreprises différentes, start-up, grands groupes et éditeurs,

38:50 c'est ce que j'ai rassemblé dans ce bouquin qui s'appelle Living Documentation. Paru en 2019 et que je me ferai un plaisir de dédicacer si j'ai l'occasion de vous croiser à l'occasion. Alors tout ce qu'on a vu là sur les termites, certains et certaines un peu vieux jeux, un peu traditionnels pourraient dire mais ça c'est pas de la vraie documentation. Alors pareil, je ne sais pas vous, mais pour moi, la vraie documentation, ça ne me fait pas rêver. La vraie documentation, c'est plutôt plein de mauvais souvenirs de documentation qui me trompe, qui n'est pas à jour, qui me raconte des choses. qui ne sont plus tout à fait vraies. C'est aussi des souvenirs de« je n'ai pas envie de la maintenir, souvent c'est plein de textes et je n'ai pas envie de m'en occuper». C'est une préoccupation que vous avez aussi quand vous posez la question, dans les questions, qu'est-ce qui se passera sur votre doc dans trois ans? Oui, on n'a pas envie de la maintenir. Et la maintenir, ce n'est pas le genre de choses qui nous accélèrent. Pourtant, la documentation, c'est censé être utile.

39:53 Moi, j'aimerais bien une documentation qui ne me ralentit pas et au contraire qui m'accélère. Alors pourquoi? Revenons un peu au fond. fondamentaux. Pourquoi on aurait besoin de documentation? Vous savez comme moi que faire du logiciel, c'est avant tout trouver des réponses à plein de questions. C'est ce qui fait que c'est super intéressant comme travail. Et plein de questions, plein de questions pour les non-développeurs. Il y a plein de questions. J'en ai mis un paquet ici, mais c'est infini. Et pour les devs, il y a plein d'autres questions. Comment je m'assure que je ne vais pas tout casser? Comment on fait ce genre de choses? Qu'est-ce qui est interdit ici? Est-ce que j'ai le droit de faire comme ça? C'est quoi la meilleure façon de faire ça? Et donc, notre boulot, pour une partie, c'est d'inventer les réponses, bien sûr, mais il y a un certain nombre de réponses qui ont déjà été trouvées et qui ont pris du temps à trouver, et on aimerait bien pouvoir les retrouver sans réinvestir tout le temps les découvrir. Donc, clairement, l'idée de la documentation, on s'en fout de la documentation. Ce qu'on veut, c'est la récupération du savoir vite, avec la promesse que si je peux accéder plus vite à du savoir, je peux livrer plus vite, je peux développer mon logiciel, l'améliorer, l'évoluer plus vite.

41:00 Donc, dans l'idéal, commençons par rêver. Dans l'idéal, notre idéal documentaire, ce serait des mécanismes, une combinaison de mécanismes qui ferait qu'on aurait accès à juste assez de savoirs. Il y a plein de savoirs dont on se fout toujours, on s'en moque complètement. Mais par contre, il y a des savoirs, ceux qui sont coûteux à retrouver ou qui sont dangereux si on ne les a pas, ceux-là, j'aimerais bien les avoir, juste ceux-là. J'aimerais bien les avoir juste au moment où j'en ai besoin et j'aimerais bien leur faire confiance. Tout ça pour que ça m'améliore. Non, ce n'est peut-être pas copilote. Alors, sur tout ça, j'ai catégorisé tout ça en quatre grands buts, quatre grands principes. On ne va pas les passer très vite, c'est plutôt une façon de grouper pour un livre. Mais donc, il faut que ce soit fiable, il faut que ça demande très peu d'efforts, il faut que ça encourage la collaboration au lieu de la décourager, parce que c'est quand même, la collaboration reste quelque chose sur lequel on veut investir. Et au passage, si on doit faire un tout petit travail, il faut que ce petit travail, en plus, nous fasse réfléchir pour améliorer notre façon de faire, notre façon de penser.

42:05 Ça nous amène des insights. Donc, ça donne plein de principes, mais là, on n'a pas le temps de les voir, on n'a que 15 minutes. Et donc, on va revenir à la fondamentale des termitières. Les termitières partagent le savoir au travers de leur travail elles-mêmes, avec des petits marqueurs en plus. On va faire pareil. La première technique, ça va aller vite, c'est déjà de se dire, minimiser le besoin d'avoir l'information. Il y a plein de choses à faire, mais je vais en décrire une essentielle, c'est que ne faites pas de pièges à vos collègues. Déjà, mieux travailler d'emblée, ça va tout aider. Vous voyez bien ici que si on avait mis les boutons dans le bon ordre, on n'aurait pas eu besoin d'étiquette. Donc, il y a plein de cas où on peut se passer de doc et on doit apprendre à le faire mieux. Le deuxième point, c'est tout ce qui est travail collectif. Travail collectif, c'est des phases, c'est bien sûr, c'est des modes de documentation. Et donc, dès que vous les regardez comme ça, d'un coup, d'ailleurs, ils deviennent plus raisonnables en termes de temps passé. Oui, ça vaut du temps, ça vaut la peine de passer. C'est du temps, toute l'équipe ensemble, même pour travailler sur une seule tâche, qu'on appelle du mob programming. C'est de l'investissement, de plein de trucs, et notamment de partage de savoirs.

43:09 Donc là, on pourra en parler des heures, mais je préfère détailler d'autres idées aussi. Et pendant que je vous montre un petit chat, parce que pourquoi pas un petit chat, ça fait toujours du bien de voir un petit chat au milieu d'une présentation, n'est-ce pas? Alors, l'autre grande idée de la doc de partage de savoir, c'est de juste admettre, exactement comme pour les termites, que la majorité du savoir que vous vous apprêtez à documenter, en fait, l'information est déjà quelque part dans votre système. Elle est juste, elle attend juste d'être libérée. L'information est déjà dans votre système, mais vous ne savez pas où elle est. Ou alors, elle est dans une forme qui n'est pas accessible, par exemple un fichier de config ou un bout de code qui n'est pas forcément visible. Elle peut être obfusquée. Elle peut être dans une forme qui n'est effectivement pas du tout digeste et elle peut aussi être éclatée partout. Et ce qui fait que ce n'est absolument pas pratique d'aller la consulter. Alors là, pour bien que l'idée reste bien dans vos têtes, je vous montre cette image magnifique. Vous avez maintenant la chanson en tête. La documentation, elle est déjà, la plupart de l'information que vous voulez documenter est déjà dans votre système.

44:13 Quelque part dans les artefacts que vous avez, dans votre code essentiellement, les tests et tout le reste. Elle veut juste se libérer, cette info. I want to break free. C'est bon, vous l'avez maintenant? Vous ne l'oublierez plus. Alors, vous savez que je suis fan de Domain Run Design. Et donc, dans Domain Run Design, moi, j'aime bien, je trouve très important de savoir c'est quoi le... langage de mon métier. J'aimerais bien avoir un glossaire. C'est quoi le langage de ce domaine métier? L'information, elle est déjà quelque part dans mon système, bien sûr. Elle est où? Elle est dans mon code, dans mes scénarios de test. Et est-ce qu'elle est suffisante? Presque, mais pas tout à fait. Peut-être qu'il faut que j'ajoute un petit quelque chose. Et donc, juste avec cette idée-là, naturellement, vous aurez l'idée de faire un diagramme, un glossaire vivant. C'est-à-dire que vous allez scanner le code. qui parle du métier, vous allez extraire l'information du langage et en faire un glossaire qui vient du code. Pourquoi on appelle ça un glossaire vivant? Parce qu'au fur et à mesure des ajouts, suppressions, renommages et déplacements de classes, votre glossaire, il vit avec.

45:15 Votre glossaire, il évolue au même rythme, seconde par seconde, si vous voulez, il évolue au même rythme que vos refactorings. Et donc là, vous avez vos glossaires, par sous-domaine, bien sûr, chacun avec sa description du module, il fait quoi mon sous-domaine, les concepts clés mis en avant, et bien sûr les entrées du glossaire, et tout ça vient de mon code. Et donc si je veux que mon glossaire soit bien fait, mon code doit être bien fait aussi, et ça m'encourage à faire du code plus propre. Alors vous avez remarqué que là, ici, j'ai fait de la mise en avant des concepts clés de mon domaine. Comment j'ai fait ça? Il a fallu que j'injecte un petit peu de savoir en plus dans mon code. J'ai un petit peu étendu mon Java avec une annotation maison. Avec un tag qui dit ça c'est une info qu'il faut mettre en avant parce que dans mon domaine ça fait partie des 4-5 concepts clés. C'est un travail que j'ai fait qui m'a coûté vraiment pas cher mais qui m'a qui facilite après l'absorption par mes collègues quand ils vont découvrir ça. C'est une idée qui n'est pas limitée à du code. Vous pouvez étendre n'importe quel endroit dans lequel il y a des infos dans votre système. Vous pouvez ajouter des tags dans Consul et cataloguer, catégoriser vos services et poser des questions à votre discovery pour savoir qu'est-ce qui parle de taux d'intérêt et qui se réfronte et qui aura un problème de perf maintenant.

46:27 Ça, c'est une réponse documentaire. Et on peut le demander à Arthur. Consul. Vos GitHub, vous avez des organisations, tout ça, c'est plein d'occasions de mettre des tags et d'augmenter le savoir, de rendre vos systèmes plus complets, avec plus d'infos et avec l'info qui manque. C'est ça les marqueurs. Vous ajoutez des petits poussettes, des petits cailloux, des petits marqueurs pour que votre système ait presque toute l'info, vous ajoutez ce qui manque pour qu'il ait toute l'info. Alors, il y a un autre bénéfice à faire ça, c'est un bénéfice avec vos collègues. Vos collègues, quand ils arrivent, ils passent, ils voient le code que vous avez légèrement, ils voient les petits cailloux, ils voient les petits marqueurs. Ces petits marqueurs peuvent contenir des choses comme des liens. Ils contiennent aussi l'auteur qui les a ajoutés. Et vos collègues, ils arrivent, ils disent, c'est quoi ce truc? Oh, il y a un lien, je clique, clac, oh, je me retrouve à lire Martin Fowler. Ça ne fait jamais de mal de lire Martin Fowler, n'est-ce pas? Ils n'ont pas compris, ils regardent qui a commité ça et ils vous posent une question. Et maintenant, vous vous retrouvez à expliquer un truc à quelqu'un qui vous a demandé de l'expliquer. Ce n'est pas top ça? Ça, c'est aussi de la documentation. qu'on vienne vous poser des questions.

47:28 Vous n'êtes pas dans la posture de prêcher. On vient vous poser une question. Alors, qu'est-ce qu'on va mettre comme petit marqueur pour être efficace? Rappelez-vous, on n'a pas envie d'écrire de prose, on n'a pas envie de passer du temps. Donc, on a envie d'être super efficace. Et là aussi, il s'avère que quasiment tout ce que vous faites, ça a déjà été fait ailleurs, peut-être même mieux. Et ça a déjà été nommé, documenté, rédigé dans la littérature. Il y a énormément d'auteurs et d'auteuses qui ont décrit plein de trucs. Et donc, au lieu... Alors, si vous vous apprêtez à écrire un peu de... Prose pour raconter un truc. Et si on passait plutôt ce temps-là à aller chercher comment ça s'appelle, ce qu'on est en train de faire, comment ça s'appelle dans la littérature. Et ensuite, il n'y a plus qu'à prendre le mot, le lien, et faire le lien avec l'élément de la littérature standard. Et au passage, on va sans doute apprendre à le faire mieux, ce qu'on est en train de faire tout de suite. Et donc, c'est une façon extrêmement économe de documenter avec de l'info déjà toute faite, avec de la documentation ready-made. Alors maintenant, imaginons qu'on veut documenter des aspects d'architecture. Par exemple, vous aimeriez bien savoir c'est quoi l'architecture en place.

48:33 Et vous avez bon goût, vous avez choisi une archi hexagonale, bien sûr. Une marché hexagonale, c'est quoi? C'est un domaine modèle à l'intérieur de l'infrastructure autour avec des adapteurs. Ce style d'architecture, il est déjà dans votre code. Ça se voit par la convention de nommage. Si vous voulez le rendre encore plus explicite, vous pourriez ajouter des annotations comme ça. La convention de nommage peut aussi suffire. Maintenant, si vous voulez le montrer à d'autres, c'est très facile de faire un diagramme généré à partir de votre code qui montre sous une forme visuelle ce qu'il y a déjà dans le code et qui le rend plus accessible au passage. C'est très facile. Il y a des exemples sur mon GitHub. C'est 40 lignes de Java. Ça se refait à chaque fois. Les projets sont tous tellement différents que ce n'est pas facile à partager, par contre. Donc, il vaut mieux refaire sa moulinette, souvent chacun dans son coin, mais ce n'est pas très difficile à faire. Ce n'est même pas une demi-journée de boulot. Alors, Et le bénéfice, c'est que si vous avez besoin de ce diagramme, vous avez un diagramme qui reste vivant. Vous pouvez ajouter des... placer, renommer des classes, les supprimer, les changer d'endroit, votre diagramme sera toujours à jour à la seconde près.

49:37 Alors ça c'est très excitant, mais il y a des pièges bien sûr. C'est que si vous faites des diagrammes générés, la tentation est grande de tout montrer, et auquel cas ils ne servent plus à rien. La règle d'or, si vous faites un diagramme, il doit raconter une chose et une seule. Mon conseil, c'est de faire le sur un papier et ensuite essayer d'automatiser ce que vous avez fait sur le papier. Et donc ce diagramme, ça nous permet aussi de réfléchir sur la qualité de notre code après. Par exemple, Vous voyez ici qu'il y a une flèche qui sort de la boîte, là, et ça c'est mal. Et donc ce diagramme met en évidence qu'on a raté quelque chose, on n'a pas respecté l'architecture qu'on s'était donnée. Et là, vous voyez qu'on est en train de faire un diagramme, mais on est déjà un pied dans ce qu'on pourrait appeler aussi de l'analyse statique. Mais l'analyse statique, ce qu'on veut ici, c'est de la documentation. Et rappelez-vous, la documentation idéale, idéale, idéale, c'est une documentation que vous n'avez même pas besoin d'aller voir. C'est ce qu'a dit Arthur juste avant d'ailleurs. Avoir l'info, ça ne suffit pas. En plus, il faut avoir une façon qu'elle vienne à vous au moment où vous en avez besoin. C'est ce qu'il propose avec Promyze et les suggestions.

50:40 La même chose, on a besoin de la même chose dans notre code aussi pour toutes les contraintes d'architecture. Et un moyen de le faire, c'est sous forme de test. Et on a de la chance parce que depuis quelques années, on a ArcUnit en Java qui nous permet de faire ça, qui permet d'écrire des règles d'architecture, de dépendance en particulier. Et vous ne pouvez les ignorer. Tant que vous les respectez, vous pouvez les ignorer. Le jour où vous ne les respectez plus, vous n'avez pas besoin de vous poser la question si vous êtes compatible parce que le système va vous le dire avec un test qui échoue et qui vous dit« Oups, t'as raté». Ce n'est pas top, ça? L'idéal, en fait, si on rêve assez fort, on peut s'en approcher d'assez près. Pas encore pour tout, mais il y a beaucoup de choses sur lesquelles on peut avancer comme ça. Alors exactement comme Maxime et Arthur ont mentionné avant, une des clés en matière de documentation et de savoir, c'est de se poser la question. de la vitesse à laquelle ça change. Il y a des infos, il y a toujours une certaine quantité d'infos qui changent très peu. Par exemple, vous avez un microservice, tant qu'il sera là, il aura sans doute le même but, ce microservice.

51:43 Et donc, la description de son but, c'est quelque chose qu'on peut faire en prose parce que ce n'est pas susceptible de changer très fort. Si ça changeait trop, après tout, on le remplacerait par un autre. Donc, c'est de l'info qu'on peut appeler evergreen content. Et là, pour le coup, des wikis, notions, confluences font l'affaire très, très bien. À une seule condition, c'est que vous soyez vigilant et vigilante dans le fait de retirer, de ne pas mettre dedans tout ce qui est volatile. Ça, c'est la clé, parce que si vous mettez de l'info qui périme dedans, Ou bien vous devrez la maintenir et c'est tout raté, ou alors quand on lira, on découvrira des choses qui ne sont plus vraies et on ne fera plus confiance à votre doc. Donc, ce sera raté aussi. Cyrille, pardon de te couper, on va devoir limiter le temps et passer à la question Q&A. Je ne sais pas si tu as encore… Alors, je vais terminer justement. Donc, il y a plein d'autres idées. C'est parfait. Et donc, pour terminer, en fait, justement, on arrive au bout. Je voulais juste terminer par le fait que tout ça, quand on veut le faire, si vous avez du mal à le faire, c'est qu'en fait, vous avez des problèmes plus graves, notamment de qualité dans votre système.

52:50 Et donc, c'est pour ça que faire de la doc et l'automatiser, ça nous donne des retours sur le fait qu'on peut améliorer aussi notre travail de base. Donc, la documentation, c'est partout. Et l'idée, c'est qu'à... avec tout ça, et essayer de remettre du fun et du plaisir dans ce travail. Merci de votre attention. Merci. Je trouvais ça vraiment passionnant. J'avais vraiment du mal à couper sur la fin. Je vais faire revenir Maxime et Arthur sur scène et on va prendre quelques questions qui ont été posées. Et juste après, vous pouvez rester si vous le souhaitez. Cyrille, est-ce que tu peux arrêter ta présentation, comme ça on retrouve l'écran? par une question pour Maxime. C'est une question de Romaric qui demande si... Tu as peut-être déjà répondu, je ne sais plus, à l'oral ou dans le chat. Est-ce que vous utilisez Notion comme outil de gestion de produits ou projets?

53:54 Est-ce que ça remplace Jira? Alors j'ai répondu rapidement. Il y a une partie de nos équipes qui utilisent effectivement Notion comme outil pour faire du Kanban ou du Scrum. Donc c'est possible. Personnellement, je ne suis pas très fan de Jira. C'est facile de choisir. Mais sinon, nous, on utilise aussi beaucoup Trello. Mais c'est possible d'utiliser Notion, ça c'est bien. Du coup, tout le système de tickets est dans Notion et il n'y a plus du tout de ticket Géra? Dans ces cas-là, oui, tout est dans Notion. C'est ce qu'on a fait chez nous pour info. On était sur Jira, tu vois, et c'était beaucoup trop lourd pour une équipe comme la nôtre avec une dizaine de personnes. Et c'est vrai que maintenant qu'on a tout sur Notion, on a fait des petits tableaux cambans pour gérer les tâches commerciales, pour gérer les tâches techniques. Et ça reste très simple avec très peu de colonnes. Dans notre cas, ça suffit. Mais effectivement, je pense qu'il y a peut-être des choses qui vont manquer.

54:54 Mais quand ce n'est pas trop complexe, ça peut suffire. Merci. Une question pour toi, Arthur. Une question, si je prends bien le prénom. Est-ce que vous avez développé Maison et quelles possibilités pour l'utiliser sur Office, par exemple? Alors, ça a été développé effectivement par nous directement depuis quelques années maintenant. Sur Office, effectivement, ça ne va pas être intégré directement. Après, on a une API REST qui est ouverte et la plupart des plugins, justement, sont aussi assez ouverts. L'objectif, c'est que les personnes puissent récupérer un petit peu, par exemple, leurs pratiques. Si je prends l'exemple de ManoMano, ils ont développé une petite roue. Une roue de la fortune où tous les matins, en fait, après le délimiting, ils lancent la roue de la fortune, ça tombe sur une pratique au hasard et ils précisent, ils expliquent un petit peu la pratique chaque jour, c'est la pratique du jour. Ça permet de voir un petit peu justement cette doc chaque jour après le délimiting.

55:56 Bon, c'était marrant, on n'avait pas du tout anticipé un truc comme ça, mais oui, ça peut se faire effectivement. Je vais prendre une question qui était aussi beaucoup votée pour Maxime. Est-ce que vous mettez des données sensibles sur Notion? Alors, il y a plusieurs niveaux de données sensibles, mais on peut dire que oui, en partie, il y a certaines données sensibles qu'on met sur Notion. Et dans ces cas-là, on fait un partage uniquement avec certaines personnes spécifiques. Et du coup, aucune autre personne ne peut avoir accès à ça. Même les admins. Il y a des systèmes de restrictions, c'est assez bien fait. On peut avoir une page, dans cette page mettre des liens vers des sous-pages avec un accès restreint, et dans ces cas-là, ça n'apparaît pas sur la page mère, et du coup ça ne fait pas bizarre. Le système est assez bien fait. Il y a encore une question pour Maxime.

57:01 Quel support technique il y a pour l'écran dans l'accueil? Ça fait référence à ta présentation. J'ai répondu rapidement. On a branché un Raspberry Pi avec Chrome et ça fait l'affaire. Je ne sais pas si c'était ça la question, Florent. Je reviens sur... Vous m'entendez toujours bien? Je vais laisser ma caméra éteinte. Parfait. Revenir sur une question pour Maxime. Je crois aussi qu'elle a été répondue dans le chat, mais elle a été beaucoup votée. Quelle formule tarifaire utilisez-vous pour Notion? Est-ce que c'est team ou entreprise? On utilise Team et le gros souci qu'on voit avec ça, c'est au niveau de la sécurité. Il y a quelqu'un qui a aussi répondu dans le chat. On ne peut pas décommissionner les gens automatiquement parce que nous, on a G Suite et Notion. On se connecte à Notion via G Suite et si on supprime de G Suite, l'utilisateur Notion n'est pas supprimé automatiquement.

58:03 Donc, il faut qu'on le fasse à la main. Et grâce à la version entreprise, on pourrait automatiser ça un peu plus simplement. Mais sinon, la version équipe nous suffit complètement. Une question pour Cyrille qui vient de Didier. Quel est le retour d'expérience des équipes qui ont adopté ta Living Documentation? Alors, personne n'a adopté la totalité de ce qu'il y a dans le livre. Ce serait idiot, de toute façon, ce serait comme... Ce n'est pas l'idée, ce n'est pas de faire un grand chlème. Par contre, j'ai pas mal de retours d'expériences positives de gens qui ont adopté une ou deux techniques. Ça, c'est le plus fréquent. Et pas sur l'entreprise entière, sur une équipe par-ci, une équipe par-là qui a du succès à faire ça. À grande échelle, il y a une organisation qui s'appelle Pôle emploi qui est engagée très vivement. Dedans avec des investissements même parce qu'ils sont nombreux et il y a beaucoup de choses à passer.

59:07 Donc là, c'est un peu plus... Donc là, c'est par exemple des glossaires vivants, documentation basée à base de Gherkin un peu à côté, dépendance, etc. Ils sont assez avancés dessus. Ce qui me permet d'ailleurs de rebondir, Living Doc, c'est un mot qui vient de Gherkin, qui vient du monde BDD, du monde des cucumbers et Specflow. Documentation vivante, ce n'est pas que ça aujourd'hui, c'est un sujet qui, comment généraliser tout ça à tous les autres aspects de connaissances. Pas que les comportements métiers. Ça me permet de rebondir sur une autre question d'Emmanuel qui demande comment faire pour que la documentation vivante par Gherkin soit lisible par tous, y compris par le métier. Normalement, elle serait facile par tous. Par définition même, les scénarios de Gherkin sont faits pour être dans le langage métier. Ils sont très lisibles, ils doivent être compréhensibles par absolument tout le monde. Par contre, pour être accessible, il faut aussi qu'il y ait un moyen de les fournir, de les mettre sur un site web, par exemple, pour tout le monde. Et donc, pour ça, le meilleur outil que je connaisse, c'était Pickles en .NET, qui est un site web avec un petit moteur de recherche intégré qui vous donne accès à tous les scénarios, un petit moteur de recherche, des tags pour les naviguer, les rechercher.

1:00:16 Et c'est donc, par exemple, les PO, les business analysts ont toujours adoré ça. Et donc, c'est l'aspect. Ça remplace complètement les specs en beaucoup mieux. Ça s'appelle le pical parce que c'est une recette à base de concombre. Pour filer la métaphore. J'ai une question qui concerne Promyze, une question de Dorian, qui demande comment sont regroupées les pratiques déclarées sous des noms différents et si les morceaux de code doivent être identiques ou semblables pour être reconnus. Alors, en fait, pour répondre à la première question, effectivement, c'est possible que plusieurs équipes créent des pratiques qui se ressemblent fortement, mais qui n'ont pas vraiment le même nom. On a la possibilité de fusionner des pratiques ensemble, en fait, dans la plateforme. Et c'est ce qui arrive régulièrement. On le voit, alors, pour citer aussi Pôle emploi, parce qu'ils utilisent les deux, ils utilisent aussi Promyze. Comme quoi, les trois solutions sont très complémentaires, parce que je crois qu'ils sont sur Confuence ou Motion aussi. Donc, voilà, les trois sont vraiment complémentaires.

1:01:16 Et en fait, on se rend compte lorsque une équipe crée des pratiques sur du DDD, par exemple, ou du Java ou du Angular, que d'autres équipes en ont créé qui sont assez similaires. Et ça permet aussi d'uniformiser un petit peu des choses. moment-là, quand on voit qu'elles se ressemblent, en disant attention, parce qu'il y a une équipe qui utilise telle lib, l'autre qui utilise celle-là, et peut-être que ce serait bien justement d'uniformiser un petit peu les choses. Donc l'objectif, ça va être de les regrouper ensemble. Et après, pour tout ce qui est suggestion automatique, aujourd'hui, en fait, ça va se faire par... similarité, donc même si le code n'est pas exactement le même, évidemment, ça va être suggéré. Par contre, si ça se ressemble un peu, ça va être suggéré aussi. Et on a aussi des systèmes de regex très simples, en fait, qui vont être capables de dire, tiens, quand j'ai tel symbole avec tel mot-clé public, etc., je vais pousser la pratique. Et c'est complémentaire aussi d'outils comme SonarCube ou des linters, pour parler de ça, parce qu'eux, ils vont faire de l'analyse statique pour regarder si les méthodes ne sont pas trop grandes, s'il n'y a pas trop de paramètres, s'il n'y a pas de duplication de code. Et c'est un autre type de recherche pour un autre type de pratique. Dans Sonar, on va voir la méthode est trop grande.

1:02:19 Et dans Promyze, quelqu'un va écrire la méthode ne respecte pas le principe de single responsibility, par exemple. Elle fait deux choses. Donc, il faudrait sortir un service métier. Donc, vraiment, il y a différents niveaux de lecture, mais l'un ne va pas sans l'autre. C'est vrai qu'aujourd'hui, toutes les entreprises qui utilisent notre solution utilisent aussi des outils de wiki interne, utilisent des outils comme Sonar ou des linters et devraient utiliser des outils de teaming documentation. Merci. Je vous propose de faire un tour de table pour donner le mot de la fin et qu'on puisse conclure avant de passer au table de networking. Maxime, tu veux commencer? Oui, comme Cyril ou Arthur vient de le dire, je trouve que les trois talks se complétaient vraiment bien. Moi, c'était plus du haut niveau. Et puis après, Arthur et Cyril au niveau du code, c'était top. Ça m'a donné envie d'utiliser leur pratique. Donc, c'était top. Et pour la suite, je suis dispo pour discuter si vous avez encore des questions sur l'étape de networking.

1:03:23 Arthur, je te donne la parole et on finira par Cyril. Oui, effectivement, je trouve qu'il faut vraiment garder en tête que ce ne sont pas des choses qui s'opposent. C'est vraiment complémentaire et ça répond à des besoins différents, comme les pratiques de développement de pair programming, revue de code, TDD, mode programming, etc. Répondent également à des besoins un peu différents et donc ça se complète. Donc, c'est important que vous trouviez le bon scénario et les bonnes manières de faire chez vous, dans votre entreprise, en fonction de vos problématiques et de votre contexte. Mais évidemment, n'hésitez pas à faire des choses dans la plateforme. Je pense que le mieux, c'est d'être agile, de tester des choses, de voir si ça marche ou pas. Ce qu'on a fait nous avec Trello, puis ensuite avec Jira, puis ensuite avec d'autres outils. Et puis au final, on est tombé sur... sur nos chaînes, mais il faut vraiment essayer et essayer d'itérer. Je pense que c'est le principal, pour trouver ce qui correspond mieux à votre contexte. Merci. Cyrille, le mot de la fin? Alors, exactement tout ce qui a été dit avant.

1:04:25 Et puis donc, pour récapituler, les wikis avec discipline pour des infos qui sont bien stables, mais avec discipline. Promyze, c'est un bon outil qui, alors je ne l'ai pas utilisé encore moi-même, mais il m'a l'air de tout cocher les cases d'un outil bien collaboratif, Insightful et tout, donc ça coche complètement, c'est aligné avec la démarche de LivingDoc. Et puis, les autres approches de LivingDoc, certaines sont tellement fun et tellement code que par contre, on peut se laisser piéger par procrastiner en jouant avec au lieu de livrer du code, au lieu de livrer votre travail. Donc, c'est aussi un des travers de LivingDoc, c'est que ça ne doit pas éclipser. Et l'essentiel qui est livré et livré vite. Voilà, et je pense que ce sera peut-être le mot de la fin. Oui, parfait. Ad hoc fun! Merci beaucoup. On va se retrouver sur l'étape de networking pour échanger. Et puis, je souhaite à tout le monde une bonne journée et bon appétit. Salut. Au revoir. Salut tout le monde. Merci.