Fabrice Flore-Thébault – Senior Technical Writer chez RED HAT

par

Interview de Fabrice Flore-Thébault

Walid : pour ce nouvel épisode, nous allons parler d’un sujet qui n’est pas abordé si fréquemment qu’on pourrait le penser dans la littérature et dans les podcasts, on va parler de documentation. Pour ce faire, j’ai invité à parler à un ami qui travaille en tant que Technical Writer (NDLR : rédacteur technique) chez Red Hat et qui va nous expliquer un petit peu, nous parler de la documentation de son métier, un peu de son passé et de ce que ça veut dire qu’écrire de la documentation professionnelle pour des projets et en particulier dans une boite comme Red Hat. Après, on pourra de prendre un petit peu ça et généraliser, regarder qu’est-ce que ça veut dire écrire de la documentation maintenant. Alors Fabrice, écoute, merci beaucoup d’abord et j’espère que tu vas bien.

Fabrice : oui, ça va bien. Merci de me recevoir. Ça fait très plaisir de t’entendre et de te voir alors qu’on est maintenant plus dans la même ville depuis longtemps.

Walid : on s’est connus alors qu’on habitait tous les deux à Bruxelles. Il a fallu qu’on aille sur un salon à Paris pour s’apercevoir qu’on habitait à deux rues d’écart à Bruxelles, ce qui était quand même assez cocasse. Première question, est-ce que tu pourrais te présenter, Fabrice, et nous parler un peu de ton parcours ?

Parcours de Fabrice

Fabrice : je m’appelle Fabrice. Je suis un Français exilé en Belgique qui travaille pour une boite américaine, qui a une petite fille belge et une femme à moitié britannique et à moitié allemande. Je suis un Européen citoyen du monde. On va dire ça d’abord. Je pense que c’est ça le truc le plus intéressant.

Je faisais des études d’histoire quand j’ai entendu parler des logiciels libres et de Linux et de Wikipédia. Et je crois que tout a commencé à ce moment-là, à un moment où je me suis dit que oui, à l’université, on nous dit la connaissance, c’est un bien commun, mais on fait beaucoup de choses pour mettre des barrières dans tout ça. Je ne sais pas. J’ai glissé dedans à ce moment-là. Ça s’est fait comme ça. Comment quelqu’un qui n’avait pas utilisé d’ordinateur de toute sa vie commence à passer des nuits à essayer d’installer Linux. J’ai mis un mois avant de trouver la commande halt pour éteindre l’ordinateur. Donc, j’ai commencé avec des trucs, genre démarrer un ordinateur, ça mettait une demi-heure parce que le petit Linux, il devait rechecker ses disques parce que je ne l’avais pas arrêté comme il faut. Donc, je ne suis pas parti avec les meilleures cartes en main, mais j’ai appris et je me suis accroché.

Et voilà, à force d’apprendre, Ça a fini par devenir aussi un travail. Et puis, j’ai vu les métiers de l’informatique évoluer très très fort depuis… J’ai commencé en 2007, 2008, quelque chose comme ça. Mon premier boulot, c’était IT Support. Tu te rappelles ? IT Crowd ?

Walid : oui.

Fabrice : voilà, ça, à peu près pareil. Dans la fiche de poste, il faut savoir soulever 15 kilos, parce que c’était au moment des écrans cathodiques et les gros écrans de designers, ils pesaient 15 kilos. C’était un métier qui n’était pas uniquement derrière un laptop, derrière un ordi toute la journée, mais il y avait beaucoup de contacts avec les gens, il y avait des trucs qui étaient physiques. Soulever un serveur de 4U… ben la première fois, tu n’enlèves pas les disques et tu te fais mal. Et après, la seconde fois, tu enlèves les disques. Maintenant que tout est dans le Cloud, soulever des serveurs, je n’ai pas fait ça depuis 10 ans au moins. Et donc, mon premier métier, administrateur système, a, je pense, à peu près disparu de la planète, parce qu’on a automatisé beaucoup de choses. Il y a beaucoup de choses qui ne se font plus du tout pareil.

Il y a beaucoup de choses qui prenaient du temps avant et qui maintenant sont immédiates. Et je pense que oui, tous les cinq ans à peu près, mon métier s’est complètement transformé parce que ce qu’on faisait avant, on ne fait plus ou on fait différemment. Donc voilà, pendant 10 ans, j’étais on call. Je me suis réveillé à 4h du matin, le jour de mon mariage, pour aller réveiller un serveur planté, un serveur qu’on avait oublié, qui était là depuis plus de 10 ans. Des trucs comme ça. Et maintenant, j’écris de la doc, alors…

Walid : donc, tu commences par faire du support. À un moment, tu commences à passer à faire de l’adminsys. Là, moi, c’est le moment où je t’ai connu, tu as commencé à travailler sur l’automatisation, la gestion de configuration, etc. Et après, tu as l’occasion de bifurquer pour rejoindre Red Hat en fait ?

Fabrice : oui, mais la vie n’est pas linéaire. On va dire, au moment où j’étais sysadmin, je me retrouvais devant des trucs où c’était un peu du parcours, si tu veux. C’est un peu installer un ordinateur, installer des ordinateurs pour les devs, c’était un petit peu parcours, fais ci, fais ça, clic clic clic clic clic clic… Le problème, c’est que la première fois, ça me plaît bien. La deuxième fois, ça me plaît moins. La troisième fois, ça m’ennuie. Et la dixième fois, je fais des erreurs parce que je ne suis plus du tout là quand je fais le truc. Donc, du coup j’ai cherché très rapidement à voir comment les trucs répétitifs, je pouvais éviter de les faire. Et c’était au moment, vraiment au tout début de la gestion de configuration. C’était un domaine très neuf. C’était super intéressant ce moment. Parce qu’il fallait déjà convaincre les gens que c’était possible, qu’on pouvait automatiser et que juste l’idée n’était pas complètement folle. Maintenant, quand on est dans un monde où si tu n’as pas de Kubernetes dans ton CV, tu vas nulle part. C’est marrant puisque Kubernetes, c’est vraiment juste quelque chose qui automatise tout.

Ou si tu ne l’as pas automatisé, ça ne fonctionne pas. Donc, on a un changement de paradigme qui est énorme. Je suis passé de gérer des postes de travail de gens et des serveurs qu’on installe à la main à maintenant, j’écris de la documentation pour un outil qui gère des Kubernetes sur des laptops. Donc finalement, j’écris ce qui reste à documenter quand on se retrouve à gérer un énorme truc entièrement automatisé.

Pendant quelque temps, j’ai automatisé des installations de serveurs, de configurations, etc. Et puis, vient le moment où Kubernetes arrive et où gérer un Kubernetes, tu ne le gères plus avec les mêmes outils, donc plus avec un Ansible. Donc, c’est un moment de remise en cause. Et je me suis demandé à ce moment-là si je préférais rester dans les opérations et gérer des clusters Kubernetes ou expliquer aux gens comment le faire. C’est à ce moment-là où j’ai basculé du côté de la doc, sachant que ce qui m’a beaucoup aidé, c’est que pendant toutes ces années-là. De temps en temps, sur des projets libres, j’ai aidé à faire de la doc.

Et pourquoi j’ai aidé à faire de la doc ? Parce que je savais pas écrire du code et que j’avais envie de rendre à la communauté des outils qui m’avaient rendu service. C’est juste une histoire de, je sais pas, de karma, de remettre la balle au centre.

Grâce à ce projet, j’ai fait les trucs qui me prenaient des plombes, je l’ai fait en plus rien de temps. Grâce à des projets d’automatisation, c’est juste, j’arrivais à faire en un mi-temps ce que je vais faire en un temps plein après. Et donc, une partie du mi-temps qui est libérée, je vais quand même un peu l’utiliser pour rendre quelque chose au projet parce que je trouve que ça se fait. Ça me gênait pas de prendre ça sur le ton de mon employeur, puisque avant, le boulot, il demandait un temps plein et que finalement, qu’une partie de ce temps que j’en dispose à ma manière en contribuant à la communauté, ça me semblait normal. Donc, j’ai appris sur des projets, sur GLPI, sur Rudder. GLPI, c’est un outil de gestion de parc informatique dont je pense que tes auditeurs ont entendu parler ou vont entendre qui vont me parler.

Walid : oui, certainement vont entendre parler.

Fabrice : et Rudder, qui est un outil aussi d’automatisation, je pense que tu les as reçus ou que tu vas les recevoir aussi.

Walid : j’espère bien. Plus tard aussi.

Fabrice : pour Rudder, C’est mon premier vrai boulot de Technical Writer pendant un été, entre deux boulots. Tout ça m’a permis de prouver à mon employeur actuel, Red Hat, que je pourrais être un bon writer. Et après, je suis arrivé là-dedans et ce n’était pas du tout comme je pensais.

Qu’est-ce qu’un Technical Writer ?

Walid : c’est quoi un Technical Writer ? Qu’est-ce qu’on entend par Technical Writer ?

Fabrice : j’ai mis trois ou quatre ans à me poser la question, à me reposer la question à chaque fois différemment et à essayer de comprendre, parce que ce n’est pas du tout ce que je pensais. Pour moi, l’informatique, c’est d’abord les outils Unix, les manpages, les commandes en ligne et puis une documentation sur un site web avec un wiki. C’est essentiellement la documentation de référence, en fait. C’est ça que j’ai le plus utilisé. En fait, la documentation de référence, c’est une documentation qui est écrite par les développeurs, qui est très, très proche du code. Les Technical Writers, ils ne vont pas vraiment toucher à celle-là. Les développeurs, ils vont faire ça bien et on leur fait confiance. En tout cas, chez Red Hat, cette partie-là, elle est faite par les développeurs et les Technical Writers, en fait, ils ne s’y touchent pas. Chez Red Hat, les Technical Writers, ils viennent là pour produire la documentation pour les utilisateurs, qui est un artefact du marketing et où on raconte des histoires. On veut raconter des histoires, finalement. Mais ce n’est pas aussi simple que ça. C’est-à-dire qu’on a eu des manuels, des guides d’utilisateurs, donc, il y a toute une tradition de manuels qui vient notamment d’IBM avec des manuels qui font des milliers de pages où on décrit tout.

Donc, il y a cette tradition qui est là. On va dire, il y a des traditions amenées par les gens qui travaillent, je pense que c’est un peu comme partout.

En gros, il y a deux familles de Technical Writers.

Il y a une famille qui, on dirait, c’est la famille à l’ancienne. C’est un peu celle dont je fais partie. C’est une famille qui est très technique, qui sont des gens qui savent écrire du code ou pas, mais en tout cas qui savent le lire, qui savent aller tester des trucs compliqués… il y a une grosse affinité au code. En général, c’est des gens qui sont passés par des par le support auparavant. C’est un peu ce que j’ai fait. Le parcours, c’est on apprend la matière technique, on apprend à répondre à des questions d’utilisateur et puis après, on apprend à formaliser tout ça.

Et l’autre famille, c’est des gens qui ne viennent pas du tout du monde technique. C’est des gens, ils peuvent écrire de la doc pour… Leur domaine, c’est le langage, c’est la communication. Ils peuvent écrire de la doc pour une centrale nucléaire. Ils peuvent écrire de la doc sur des tubes de dentifrice, sur des tracteurs, des canons.

En fait, c’est marrant parce que c’est des gens, ils peuvent vraiment changer d’industrie assez facilement. C’est des gens qui vont développer des techniques pour interviewer les gens, pour réussir à expliquer des choses qu’eux-mêmes ne ne comprennent pas. C’est un peu comme des… beaucoup plus proche de ce que font des interprètes, qui font de la traduction. C’est-à-dire que quand tu fais de la traduction, tu n’es pas nécessairement… et que tu maîtrises la langue, tu ne maîtrises pas nécessairement auparavant tout le côté technique, toute la technique de ce que tu traites.

Il y a ces deux profils, donc un profil plus éditorial, plus du monde de l’édition, et un profil plus technique. Je ne saurais pas dire pour toute l’industrie informatique. Je sais dire un peu pour Red Hat.

Et donc, du coup, ça pose pas les mêmes contraintes quand tu veux documenter du logiciel, parce que tu vas avoir soit des gens qui sont très autonomes pour écrire, soit des gens à qui il faut expliquer beaucoup de choses. Parce que les gens dont le point fort c’est le langage, ils vont interviewer les gens et demander: alors, comment tu fais, etc.

Donc, le brouillon est largement fait par les développeurs et ensuite, si le Technical Writer va tout changer.

Walid : il y a un truc que tu sembles un peu passer sous silence, c’est que tu n’es pas juste technique, c’est que tu proviens… enfin avant, tu as fait l’université, tu as fait des études où tu étais amené à écrire en vrai bon français ou anglais, bref, je ne sais pas. C’est-à-dire que pour avoir travaillé avec toi, moi, je ne suis pas capable. Déjà, un, j’avais plus de mal à me mettre à la place de l’utilisateur que toi et deux, je ne suis pas capable d’écrire… c’était plus compliqué pour moi, par exemple, d’écrire dans un français, bon français comme toi et de vulgariser et de raconter ce que tu appelles la belle histoire, qui a été ma deuxième question: c’est quoi une belle histoire ?

Fabrice : oui, moi, j’ai fait aussi, c’est vrai, j’ai fait des études d’Histoire, mais de Lettres en même temps. La doc technique, c’est un genre littéraire hyper pauvre en fait. On essaye de transformer le langage naturel, dans mon cas, c’est plutôt l’anglais, on essaye de canaliser un langage naturel qui est rabelaisien. Chaque personne a ses tics de langage. Un Américain, un Canadien, un Anglais, un Britannique, etc. C’est leur langage natif, l’anglais, mais ils ne vont pas parler pareil. Un rédacteur technique, il fait disparaître ça, il va gommer tout ça. Le but, c’est que la documentation puisse être lue par un peu n’importe qui dans le monde et surtout des gens dont l’anglais n’est pas du tout le langage maternel. On a un vocabulaire le plus pauvre possible, on a des structures de phrases les plus pauvres possible et aussi, on essaye de garder une structure de contenu qui soit toujours la plus prédictible possible, la plus simple possible, la plus saucissonnée possible. En fait, on essaye de parler à l’œil et directement au cerveau avant même que les gens lisent les mots. C’est-à-dire que là, je regarde juste en même temps, je regarde le fichier que tu as préparé, c’est exactement ça, c’est des checklists.

Chez Red Hat, par exemple, on a trois types de contenus et pas plus. On a une procédure qui est le type de contenu qu’on utilise le plus possible, dont la structure est définie et dont on ne dévie pas. Et une procédure, c’est : il y a une intro d’une ou deux phrases qui expliquent en gros aux gens pourquoi ils ont envie de lire cette procédure. Pourquoi faire ? C’est le pourquoi. Ensuite, il y a un petit sous-titre qui dit : prérequis. Et on liste une liste bullet points de tous les prérequis avant, tous les trucs qu’il faut avoir fait avant. Ensuite, une procédure qui est une liste numérotée de tous les steps à faire pour faire quelque chose. Et puis ensuite, une autre liste de points à vérifier et ensuite une liste bullet de ressources additionnelles qu’on peut aller voir après. Et voilà. Et donc, du coup, c’est tout le temps pareil. C’est tout le temps pareil. Donc, un utilisateur, il sait que déjà, qu’il va avoir cette information-là. Donc, il y a ce truc-là. C’est d’une pauvreté horrible, mais on n’est pas là pour faire de la création. C’est exactement l’inverse de la création littéraire, par exemple.

Donc, on a un type qui est comme ça, un type de contenu qui est une documentation de référence, mais que, je ne sais pas, sur un projet, il va y avoir une documentation de référence et 25 procédures et des concepts qui sont pareils, qui sont un chapitre. On explique les trois concepts sur le projet et basta. Il y a juste les concepts et les références qui sont un peu plus libres dans la forme, mais le gros du truc, c’est ça. Quand on prend une procédure qui est écrite par…, un brouillon, qui est écrit par un développeur, par exemple, il y a de fortes chances qu’il ne reste pas une seule ligne de ce qui était là au début. Parce qu’on met tout ça dans un ordre logique pour pas que des informations arrivent en cours de route. Donc ça, c’est hyper important. Les prérequis, on les balance en prérequis. Les phrases, on les simplifie. C’est sujet, verbe, complément, point. Le but, c’est d’utiliser le moins de mots possible pour raconter quelque chose que tout le monde va comprendre sans l’ombre d’un doute, sans dans un endroit où deux personnes vont interpréter la chose de manière différente.

C’est rigolo d’arriver à se dire : je vais supprimer 500 mots à ce texte ou des trucs comme ça, ou comment réduire le nombre de steps de la procédure de 15 à 7. Voilà, quand on utilise des petits trucs.

Concepts d’upstream et de downstream

Walid : est-ce que tu pourrais expliquer, pour les auditrices et auditeurs qui ne connaissent pas, ce que c’est que l’upstream, qui est un mot qu’on entend beaucoup dans le logiciel libre, et le downstream, qui est un mot que j’avais assez peu entendu, à part potentiellement chez Red Hat. Est-ce que tu peux expliquer de manière simple ces deux mots-là, pour qu’ensuite, derrière, après, on puisse commencer à parler justement de la collaboration ?

Fabrice : ok ça c’est une manière assez particulière, c’est le business model de Red Hat. La manière dont Red Hat fonctionne, c’est de fonctionner avec des projets qui sont upstream, c’est-à-dire c’est les projets qui sont les projets open source et qu’on va retrouver, je pense, sur GitHub, essentiellement, GitLab, très peu. C’est marrant parce que chez nous, GitLab, c’est plus les repositories downstream, donc les repositories pour les produits qui sont dans le VPN et donc auxquels des gens extérieurs à la boite n’ont pas accès. Donc, on va, à partir d’un projet upstream, on va fabriquer un produit downstream. Et le downstream, c’est juste créé à partir de upstream.

C’est juste la métaphore de la source. Open source, une source, elle vient de la source. Donc upstream, elle vient de quand c’est un ruisseau. Et downstream, si tu descends et tu vas retrouver le fleuve.

Walid : sur les projets sur lesquels tu bosses, tu as toujours un upstream qui est le projet open source et un downstream qui est le produit commercial Red Hat.

Fabrice : exception : le projet où pour l’instant, on n’a pas de downstream. De manière générale, oui, Red Hat, participe à des projets et ensuite, ils vont construire un produit où la valeur ajoutée de Red Hat, c’est l’audit de sécurité, c’est faire tourner le bazar dans le cadre d’une grande entreprise, c’est-à-dire à intégrer avec les backups, intégrer avec des authentifications centralisées, intégrer avec vraiment tout le bazar qu’il y a dans une grande entreprise pour faire tourner quelque chose. Il ne suffit pas de faire une application qui fait des petits Mickeys. Pour accéder aux petits Mickeys, il faut que tu puisses s’authentifier par le SSO de la boite. Et puis, il faut que les petits Mickeys, on puisse les « backuper » avec l’outil de backup de la boite. Le projet, lui, se concentre sur la fonctionnalité. Je montre des petits Mickeys. La partie « productisation » s’assure de tout le reste. Donc tout ce qui est sécurité, gestion des patchs de sécurité, etc. Tout le delivery vers le client aussi, c’est packagé et c’est plus facile à installer. Ça a un impact sur les projets à chaque fois. C’est qu’un projet qui va son petit bonhomme de chemin juste à faire des features, quand il doit être « productisé », transformé en produit, ça ralentit beaucoup le développement parce qu’il faut vérifier que ça et ça, c’est compatible.

Je suis sur un projet, là, maintenant, qui s’appelle Podman Desktop. On cherche à aller vraiment très, très vite et on n’a pas de produit. C’est entièrement communautaire. C’est assez rare, mais pas complètement rare chez Red Hat, parce que si on pense bien, Ansible, c’est l’outil d’automatisation qui a tué tous les autres outils d’automatisation. Red Hat a mis beaucoup de temps à voir comment transformer ça en produit.

Walid : est-ce que tu peux citer une ou deux références upstream versus downstream dans le cadre de Red Hat ?

Fabrice : la distribution Linux Fedora, c’est l’upstream de la distribution Red Hat Enterprise Linux. Pour les gens qui sont dans le monde Linux, ça, c’est peut-être le plus évident. Ça s’est encore complexifié puisque CentOS… CentOS était un downstream de Red Hat : ils reprenaient la distribution de Red Hat et il la repackagaient en libre. C’est-à-dire que ça faisait upstream, downstream et ça retournait à upstream. Red Hat a retourné ça dans le même sens que le reste. C’est-à-dire que maintenant, CentOS est plus un upstream qu’un downstream.

Kubernetes, c’est l’upstream pour OpenShift. Qu’est-ce que fait Red Hat ? On rajoute par-dessus Kubernetes, tout ce qui est sécurité et tout ce qui est nécessaire pour faire fonctionner Kubernetes dans le monde de l’entreprise. Ce qui fait que de manière générale, un container qui va marcher sur Docker, sur Podman, sur un container engine, qui va ensuite fonctionner sur Kubernetes, ça va se vautrer sur OpenShift. Les prérequis de sécurité pour faire tourner des choses sur OpenShift montent la barre assez haut.

Formats et outils de documentation

Walid : quand tu es Technical Writer, comment tu t’intègres dans les projets ? Quelle est ta relation avec les développeurs, les gens du marketing ? Quelle est ta relation avec les communautés ?

Fabrice : ça dépend beaucoup comment on organise le flux de la documentation. C’est-à-dire, est-ce qu’on met une équipe de writers upstream et une équipe de writers downstream ? Et puis, en fait, il ne se passe pas la soupe. C’est un peu ce qui se passe entre Fedora et RHEL. C’est beaucoup le cas d’avoir des trucs où le passage des deux ne se fait pas. Ou tu choisis de faire la documentation dans le projet upstream, comme ça, elle est visible dès GitHub. Tu vas sur GitHub, tu vois la documentation sur GitHub, tu as la documentation complète. Ça, c’est Ansible, AWX. Il y a beaucoup de projets comme ça. Mais c’est quand même pas la règle chez Red Hat, c’est plus compliqué techniquement. Il faut avoir la pipeline qui permet de transformer ta documentation upstream avec le nom du projet, par exemple, en une documentation dans downstream où ce n’est plus le nom du projet, c’est le nom du produit. Il faut avoir des trucs solides pour faire ça. On fait des trucs bien, il y a des projets qui font des trucs bien. On a la chance, c’est un super projet qui s’appelle Antora. Antora qui est un outil de gestion de contenu, de documentation fait en AsciiDoc.

Il y a AsciiDoc, le langage, qui est un langage de markup comparable à Markdown ou à reStructuredText, juste la spec du langage. Après, on a Asciidoctor, l’implémentation dans plusieurs langages de quelque chose qui s’est transformé, ce markup, en autre chose : du HTML, du PDF, du epub, des slides. Et ensuite, Antora, qui est un projet qui permet de faire un vrai site de doc. C’est-à-dire faire un vrai site de doc avec une navigation. Donc, ça va gérer la navigation, ça va gérer les liens, ça va gérer les versions, ça va gérer le fait qu’on va chercher des bouts de docs dans du code où le contenu est écrit à des endroits différents, mais qu’on veut les publier tous au même endroit. C’est un outil magnifique. Pour moi, c’est très comparable à Ansible à faire des playbooks parce qu’on assemble des trucs qui viennent de partout. On arrive à avoir des pipelines assez complexes et qui font des belles choses. C’est-à-dire qu’on peut avoir en cinq minutes le contenu est « mergé » sur le projet upstream, il est publié directement sur la documentation upstream, on va dire, toutes les nuits ou même au moment du comment, le contenu arrive dans le produit. On peut être tech writer et faire de l’automatisation.

Walid : t’as fait il n’y a pas très longtemps, une conférence au FOSDEM sur le sujet. Je mettrai le lien dans tous les cas dans les commentaires. Si je comprends bien, tu prends tes connaissances en gestion de configuration et en automatisation et tu as appliqué ça à la doc.

Fabrice : pour l’instant, j’aide pas mal mes collègues. Il y a des gens qui veulent faire pareil, en tout cas. C’est un exemple, ce n’est pas le seul projet où ça arrive. Ce qui a peut-être été différent sur mes projets, c’est que c’est le Technical Writer qui a fait le boulot et ce n’est pas des devs. Il y a des extensions pour Antora qui sont arrivées il y a un an. On a commencé à les utiliser quand elles n’étaient pas sorties du four. On a utilisé vraiment des trucs très nouveaux. Dan Allen, le gourou d’Antora, il bosse aussi pour des boîtes qui ont des grosses docs et des gros besoins. Il est arrivé à faire un truc assez génial, c’est qu’il a un boulot de développeur de logiciels, de documentation, il fait tout. Il a développé les specs, il a développé l’interpréteur de base, il a développé tous les outils autour. C’est juste impressionnant de le voir travailler, de le voir aussi gérer la communauté parce que qui est très présent pour répondre à la communauté des utilisateurs. Ce mec est une bête, c’est incroyable. Et quand on compare ça au bazar que c’est côté Markdown, il n’y a pas photo.

Le Markdown tout nu avec rien d’autre, on ne fait pas grand chose. Tous les gens qui utilisent du Markdown, ils rajoutent des extensions par dossier, ceci, cela. Il y a des flavors de Markdown à n’en plus finir. Pour l’instant, c’est en train de se reconcentrer sur un truc qui s’appelle MDX (Extended Markdown), qui, en gros, on essaye de reprendre ce que est-ce qui fait depuis des plombes et de le mettre dans Markdown. Mon projet actuel, c’est du Markdown et je ne suis pas hyper fan, mais les développeurs adorent.

Qui écrit la doc et avec quelles contraintes ?

Walid : là, ton passé dans l’automatisation influe direct sur tes capacités à automatiser la doc. Ça, c’est assez intéressant, mais pour ceux qui veulent en savoir plus, je pense que la conférence du FODSEM, elle explique ça très bien. Il y a un truc, quand on a préparé, qui m’a beaucoup intéressé, c’est l’évolution de la documentation. Ce que tu me disais quand on a commencé, c’est que la documentation, au tout départ des projets libres, c’était fait par les développeurs, parce que les développeurs, en gros, c’étaient des gens qui sortaient de grandes universités, etc. Ils avaient le niveau.

Fabrice : et leurs utilisateurs aussi. Ces trucs-là, ça vaut toujours la peine de faire des parallèles avec d’autres inventions. Par exemple, la lecture. On prend la lecture au Moyen Âge. La lecture au Moyen Âge, il y a très peu de gens qui savent lire, il y a très peu de gens qui savent écrire. Tout ce qui est écrit est fondamentalement écrit pour des gens qui ont le même niveau d’éducation que la personne qui écrit. Ça donne des trucs complexes. On n’a pas de Picsou Magazine, on n’a pas ce genre de trucs là. C’est quelque chose qu’on va retrouver dans de l’iconographie, qu’on va retrouver dans la peinture, dans d’autres trucs, mais qu’on ne va pas retrouver dans l’écriture. L’informatique, c’est pareil. On a commencé à avoir des gens qui étaient tous avec d’énormes universités, qui ont un parcours universitaire de minimum 10 ans avant de s’occuper d’informatique. Donc, c’est des gens, ils ont du vocabulaire, ils ont une capacité d’énonciation et de d’énoncer des choses complexes qui est très forte. Mais ils parlent aussi à des gens qui ont du vocabulaire et qui ont une capacité à comprendre des choses, des choses complexes.

On veut que n’importe quel logiciel soit utilisable par quelqu’un qui a fait son premier cours d’anglais le mois précédent et qui a un vocabulaire de 150 mots.

Pareil pour les développeurs. Un développeur maintenant, c’est quelqu’un qui a fait des études beaucoup plus spécialisées qu’un développeur des années septante. Un développeur des années septante, il y lit Kant. Il n’y a pas de problème pour ça, je pense. Un développeur des années 2020, il y en a qui peuvent, mais il y en a qui ne peuvent pas. Ce n’est pas dire quelque chose de méchant de dire ça, mais c’est juste qu’on n’est pas au même niveau d’éducation. On n’est pas du tout dans le même genre littéraire, on va dire. Donc, il y a ça. Et puis, il y a aussi qu’on est passé d’une documentation qui est essentiellement une documentation de référence, c’est-à-dire : « Mais qu’est-ce que ça fait ? Comment je peux faire pour faire ça ? Et je vais lire un truc, je vais regarder toutes les options, etc, et je vais trouver la mienne », à un truc où c’est plus le marketing qui est là. C’est-à-dire que moi, je pense que la doc, maintenant, c’est un outil de marketing où quelqu’un qui ne connaît pas le produit doit voir des histoires, doit voir comment utiliser le produit, pourquoi faire. On raconte des histoires et les histoires vont amener des features de l’application.

Ce qu’on cherche à ne pas faire du tout, c’est d’avoir une recopie de l’application. On n’est pas en train de décrire l’application. On est là pour amener les gens à utiliser l’outil. On n’est pas en train de décrire l’outil, on est en train d’expliquer pourquoi l’utiliser, comment l’utiliser et vers quoi tendre.

Walid : si on reprend au début du logiciel libre, les développeurs, étaient capables d’écrire les manpages, ce qui est globalement toujours le cas, et ils étaient capables d’écrire toute la doc qui était technique en plus, et c’est eux qui faisaient tout. Or maintenant, en gros, le développeur, il écrit toujours la doc de référence, qui peut être une manpage ou autre chose. Et à côté de ça, il y a toute une population d’autres gens qui vont faire les docs additionnelles. Toi, le Technical Writer, tu vas écrire les cas d’utilisation, l’histoire, etc. Et après, il y a, de part aussi l’évolution d’Internet et l’évolution des usages, tu as aussi tout un ensemble d’autres ressources que tu as à ta disposition, que tu n’avais pas forcément à ta disposition à côté, qui vont te permettre de pouvoir aussi apprendre et sur lesquelles toi, je pense, tu ne travailles pas trop. Je pense à, par exemple, les tutoriaux, les vidéos. Moi, par exemple, dans le no-code, énormément de posts LinkedIn, de live Twitch, etc. Donc, c’est encore des populations différentes qui ne cohabitent pas forcément avec ce que tu fais.

Fabrice : je voulais parler aussi d’une tradition chez les Technical Writers, qui est le le manual of style, le style guide. C’est quelque chose qui est super important. Donc le Chicago Manual of Style, il date des années 20, je pense, quelque chose comme ça. Il y a eu un manuel de style qui est une espèce de Bible qui explique comment tu écris de la documentation. Peu importe pourquoi. C’est comment tu écris un contenu factuel qui décrit quelque chose, etc. Ça définit comment tu utilises les virgules. Ça explique qu’il ne faut pas utiliser la voix passive parce que la voix passive, ça a introduit de l’incertitude, etc. C’est le pacte de base du Technical Writer. C’est la Bible du Technical Writer. C’est ce qui fait que les Technical Writers qui font de la doc vont difficilement passer à un autre média, vont difficilement passer à faire de la vidéo ou faire des slides ou faire des cours, etc. C’est à cause de ce manual of style qui est quelque chose qui est très formatant.

Quand j’ai commencé chez Red Hat, j’avais l’impression que mon rôle, c’était vraiment police du langage. Je m’attendais à avoir un rôle d’explorateur et de création, mais non, la plupart du boulot, c’est chiant. C’est juste : « Non, tu as de la voix passive, il faut enlever », « Non, ne fais pas les virgules comme ça », « Non, dans les titres, on ne met pas de capitales ou des trucs comme ça ». Je ne connais pas bien métier de l’édition, de l’édition littéraire.. enfin édition, les gens qui font des livres quoi, mais je pense qu’il y a aussi des strates comme ça de métiers entre l’éditeur qui fait changer la structure d’un ouvrage en entier et le correcteur qui va trouver les typos et les virgules manquantes et les trucs comme ça. Et donc, je pense que dans le boulot de Technical Writer, on a un seul titre, mais il y a tous ces rôles qui se retrouvent aussi. On est dans le monde de l’édition, mais structuré un petit peu différemment. Éditer des bouquins, le métier de faire des bouquins et de faire des guides et d’écrire, ce n’est pas le même métier que le métier faire de la radio, enregistrer des blogs ou de faire des films. Fondamentalement, ce n’est pas du tout le même métier. Ça ne demande pas de maîtriser la même chose. Ça ne demande pas de maîtriser le langage écrit et le langage oral, ce n’est pas les mêmes codes.

Je sais que cet exercice, par exemple, de participer à un blog, pour moi, c’est un truc entièrement différent de mon quotidien.

Walid : en gros, je te fais un parallèle avec… il y a quelques années, on a monté avec d’autres personnes une boite, on fabriquait des patins à roulettes, tout ce qui concernait la communication et le marketing, tout ça, c’était intégré. C’est-à-dire que tu pouvais pas communiquer sur un médium si tu communiquais pas sur un autre et comprendre qu’est-ce que tu allais sortir à quel moment et comment tu allais parler de ton produit sur tel média versus tel autre, ce n’était pas la même chose, etc. Donc ma question était aussi de savoir : est-ce que vous, vous avez un rôle dans tout ça ? Et potentiellement, il y a peut-être d’autres gens au marketing qui ont un autre rôle et savoir est-ce que vous, vous étiez en contact et il y avait une coordination quelconque ?

Fabrice : on va dire, il y a des docs, ça serait bien qu’ils soient prêts pour des releases, par exemple, des trucs comme ça. On est comme des encyclopédistes face aux journalistes. Le contenu qu’on propose, c’est beaucoup plus proche d’un contenu d’encyclopédie et c’est beaucoup moins proche d’un contenu de journaliste ou de blogueur. Le blogueur, il est dans l’événement. Il est dans le « Je délivre un truc ici et maintenant ». Ici et maintenant : message. Alors que quand tu fais de la doc, tu essaies de faire un truc qui va survivre au temps. C’est-à-dire, je vais essayer un blog, je vais mettre un screenshot avec la version d’aujourd’hui et maintenant, je vais faire une vidéo avec ce qu’il y a aujourd’hui et maintenant dans l’application. Tu ne fais pas ça dans de la doc parce que tu vas faire exactement le contraire. Tu vas faire le moins possible de screenshots, parce que c’est trop de la maintenance et c’est trop de la perte de temps. S’il y a la version du produit dedans, il faut mettre à jour à chaque version. Et du coup, les screenshots, s’il y a un revamp de l’interface utilisateur, c’est tout à refaire. Donc, on a des objectifs qui sont quand même très, très, très différents.

Là, j’ai fait récemment un blog post pour le projet. C’est sorti un peu comme de la doc qui est mis dans un blog. Je ne suis pas hyper fier de moi, mais je me suis bien rendu compte que c’était un exercice très différent. Ça a été très difficile pour moi de passer de la doc qui est très froide à un truc un peu plus convivial. Et comme je suis habitué à écrire de la doc, on enlève les mots, qui est très squelettique. Ça a été de remettre un peu de liant là-dedans. C’était le challenge du truc. Je ne suis pas trop sûr d’être arrivé, mais voilà.

« Productisation » de logiciels libres

Walid : combien il y a de Technical Writers chez Red Hat, par exemple ?

Fabrice : je crois qu’il y en avait plus d’une centaine. Je ne sais pas si c’est juste un prono ou en général. Ce n’est pas non plus énorme. On est à un ratio de 1 pour 15 développeurs à peu près, je dirais, quelque chose comme ça, 1 pour 10, 1 pour 15. Là, je suis sur un projet où il y a moins de 15 développeurs quand même et je suis un writer dedans, c’est assez exceptionnel. Le projet où j’étais avant, pour l’instant, ils sont trois. On a été trois à un moment où il y avait 40 développeurs.

Walid : quel est l’impact de mettre des Technical Writers sur le projet ? Est-ce que ça accélère le projet ? Est-ce que ça freine le projet ?

Fabrice : en général, on met des Technical Writers quand on fait de la « productisation », c’est-à-dire au moment où on freine. La « productisation », elle freine le projet, forcément. C’est là où on va mettre des QA, donc des gens qui font de la qualité, des tests. On va mettre des testeurs, on va mettre de la doc. Je ne dis pas que c’est les writers qui ralentissent le projet, mais les writers, de manière générale, sont très liés avec des trucs « productisés » qui vont lentement. Pour moi, qui venait plus d’un monde de société de services où on délivre vite et on va faire une review et puis après une autre review. Pour moi, ça peut prendre du temps parce qu’on va avoir une review où c’est les développeurs qui vont dire : oui, techniquement, ça marche. Puis après, on aura une review où c’est d’autres writers qui vont dire : oui mais tu n’as pas suivi le style guide. Donc oui, c’est plus long, mais ce n’est pas nécessairement le cas. Moi, là, j’essaie de suivre sur un projet uniquement communautaire, ils sont une demi-douzaine et les trucs, ça file super vite. Donc, si je fais un screenshot le lundi, le vendredi, c’est plus ça.

Et les gens pensent que c’est facile et que ça va vite d’écrire de la doc. Et ce n’est pas le cas. Ce n’est pas facile et ça ne va pas vite.

C’est-à-dire que quand tu écris une procédure, d’abord, il faut arriver à trouver le déroulement logique et arriver à pour faire le truc qui est dedans. Ça, ça prend déjà un bout de temps. Ensuite, il faut vérifier qu’il n’y a pas quelqu’un qui va mal comprendre le truc et qui va faire autre chose. Il y a tout ça. Il y a à rendre conforme après au langage, mais ce n’est pas le plus complexe. On a des outils maintenant pour ça. On a comme des linters de code, mais des linters pour la doc, donc qui disent : non passive voice tu n’as pas le droit. Ce genre de choses-là, il faut tester, puis après, il faut valider. Et puis après, quand c’est quelque chose qui va de upstream à downstream, il faut aussi s’assurer que ça passe bien en downstream. Notamment qu’on n’introduit pas des exemples qu’on ne peut absolument pas mettre downstream ou des trucs comme ça.

Walid : deux questions là-dessus. Quels sont les outils que vous utilisez ? Et la deuxième, c’est : tu disais tout à l’heure que tu étais en capacité de tester. Tu dis qu’écrire de la docs, ça prend du temps. Est-ce que ça prend du temps aussi parce que tu vas installer l’outil et tu vas le tester fonctionnellement ?

Fabrice : tester le truc, c’est presque ce qui prend le plus de temps. J’essaie de ne pas faire perdre leur temps aux développeurs. Donc, j’essaie de trouver les choses par moi-même, et j’ai tendance à péter des trucs beaucoup aussi. Ce qui est lent aussi, c’est que les gens qui écrivent la docs, c’est les premiers utilisateurs pour les développeurs. Les développeurs, ils sont focus sur une fonctionnalité et juste la fonctionnalité qu’ils sont en train de faire. Mais ils ne sont pas utilisateurs du produit fini, très peu. Il y a un moment, j’avais discuté avec des gens qui font un fork de PostgreSQL, donc logiciel de bases de données. Et moi, je leur parlais en tant qu’ancien opérateur de bases de données, genre les trucs à quoi il faut penser quand on fait des bases de données. Donc quelqu’un, un développeur qui écrit du code pour faire de la base de données depuis 20 ans, 25 ans. Et à un moment, la conversation a tourné court parce qu’il me dit : Non, mais moi, je n’ai jamais été opérateur d’une d’un gros serveur de base de données. Je ne vois pas de quoi tu parles.

Donc, les writers sont les premiers utilisateurs. En général, quand on utilise, c’est pour aller documenter une feature qui est nouvelle. En général, on documente une feature un petit peu pas très mature, donc on voit les trucs qui font mal. On fait : oui, mais regarde dans tel cas ça ne marche pas, etc. Il y a aussi toute une partie. En tout cas, moi, c’est comment moi je fais mon boulot. Il y a toute une partie qui est de remonter les informations sur les trucs qui ne vont pas. Après, est-ce que j’ouvre des tickets sur GitHub ou est-ce que j’envoie des trucs sur la messagerie instantanée ? Qu’est-ce qui va le mieux ? Ça, ça dépend de la relation avec l’équipe, avec les développeurs, etc. Moi, je suis pour le Agile Manifesto, version early 2000 : « Individuals and Interactions before Processes and Tools« . Donc, le travail, c’est d’abord des gens, c’est d’abord des interactions. Ensuite, on met en place des process et des outils, mais ce n’est pas les process et les outils qui sont importants. Je pense que ça, c’est vachement important pour quelqu’un qui fait de l’automatisation, aussi de savoir que ce n’est pas les tools qui sont importants, c’est les gens.

Walid : justement, tu parles d’outils, là. Vous utilisez quels outils ? Là, tu parles de GitHub.

Fabrice : le truc important, c’est que c’est de la documentation pour des logiciels. La documentation, c’est pour des logiciels. On essaie de la mettre le plus proche possible du code des développeurs. Après, il y a des débats, il y a des gens qui disent : il faut un repository à part, etc. Mais de toute façon, ça va être… Si les développeurs écrivent du code, c’est dans des repository Git, la documentation, ça va être dans des repository Git aussi. Il n’y a pas de discussion là-dessus. Alors, mettre dans le même repository ou un repository à côté, finalement, ce n’est pas une grosse variation. Mais c’est dans un repository Git. Il y a un assez grand nombre de langages de markup différents qu’on peut choisir. Donc, Pour partir des plus anciens, mais en restant dans le monde de l’open source, il y a LaTeX, mais je pense que peu de gens vont écrire LaTeX maintenant. LaTeX s’est fait plutôt détrôner par le XML dans les années 2000. Et pour la documentation, on a quelque chose qui s’appelle DocBook, qui est du XML pour faire de la doc. À un moment, les développeurs chez Red Hat, ils ont quand même, à un certains point, ils ont dit : non, DocBook, ça pue, on ne veut pas contribuer. Il faut nous trouver autre chose pour qu’on contribue à la doc.

Alors, on a dit : d’accord, on va faire autre chose. Et c’est comme ça que AsciiDoc est arrivé. On pouvait faire du Markdown, du reStrcturedText ou du AsciiDoc. À ce moment-là, AsciiDoc avait un convertisseur qui pouvait traduire du AsciiDoc vers le DocBook. Toute la chaîne de build de Red Hat, c’était basé sur le DocBook. Donc, pour l’instant, on est encore dans cet héritage-là, puisqu’on a du AsciiDoc qui est transformé en DocBook et qui va dans l’ancienne l’ancienne pipeline qui a été vraiment créée par Red Hat. La libXML, elle a été créée par Daniel Veillard qui est maintenant… je bosse avec lui, je suis trop fier.

Walid : en dehors du langage utilisé pour faire la doc, avec quels outils vous collaborez ?

Fabrice : déjà, Git, GitHub, GitLab. Chez Red Hat, les projets sont sur GitHub et les produits sont sur GitLab. On a deux plateformes Git différentes. Github, il y a tous des outils d’utilisation qui sont sur les actions, les pages, etc. Ça, on utilise assez extensivement. GitLab aussi, tout ce qui est automatisation, les conteneurs, et GitHub et GitLab savent utiliser des conteneurs, aller « puller » un container et faire des trucs dans le container qui est « pullé ». Ça, c’est une technologie qu’on utilise un peu tout le temps. Du coup, les gens utilisent chacun leur IDE préféré, leur éditeur préféré, si tu veux. Visual Studio Code est très présent. En fait, on utilisait beaucoup Atom et puis Atom a été abandonné par Microsoft au profit de VS Code. Une grosse minorité qui est sur IntelliJ Community. Moi, j’utilise beaucoup parce que l’extension pour AsciiDoc est juste merveilleuse, c’est juste trop bien. Il y a des gens qui disent Vim, Emacs, Kate, d’autres trucs.

Walid : pour tout ce qui est chat, par exemple ?

Fabrice : je pense que maintenant, la plateforme officielle, c’est Slack. Pendant longtemps, on Il y avait Slack, Google Chat, IRC en parallèle et plus après des projets qui ont d’autres outils, genre Mattermost, Discord. Mon projet, il est à la fois sur Discord et sur Matrix IRC. Moi, j’ai arrêté au bout de deux semaines d’utiliser Discord, je n’en pouvais plus des messages de pub dedans. Les projets amènent leur truc. Quand le projet, en plus, il est chapeauté par une fondation ou une autre, la fondation amène ses outils, ces recommandations, ces trucs. Et après, il y a des trucs qu’on peut utiliser ou pas en fonction. Genre la Fondation Eclipse, eux, ils sont sur GitLab, ils refusent d’utiliser JIRA, par exemple. Donc, on ne peut pas mettre un projet chez JIRA si c’est pour la Fondation Eclipse, donc il faut que ça reste sur autre chose. Vous voyez ? Oui, JIRA. Pour tout ce qui est produit, c’est JIRA. Pour tout ce qui est upstream, souvent, c’est très, très suffisant GitHub.

Documenter le no-code

Walid : ça m’amène sur la dernière partie que je voulais aborder, dont on a parlé un peu avant et sur lequel moi, j’ai beaucoup réfléchi, puisque c’est le domaine dans lequel je suis maintenant, qui est toute la partie no-code, low code. Donc toi, tu fais plutôt ce qu’on appelle du doc-as-code. Et le problème, c’est comment tu fais de la doc quand il n’y a plus de code ? C’est un domaine assez intéressant, surtout quand, comme moi, tu viens du développement et que tu arrives dans des outils dans lesquels tu ne développes plus ou assez peu. Comment est-ce que tu fais ça ? Quand on parlait, tu me disais : oui mais en fait, justement, comment ça marche ? Avec les outils grand public et les outils qui sont utilisés de manière générale, par exemple, nous, on a une communauté française du no-code où il y a à peu près 10 000 personnes, quelque chose comme ça. Et finalement, même les gens qui font beaucoup de no-code, il y en a quand même une grosse partie qui ne font pas de docs. Pourtant, comme je dis à chaque fois, quand tu es un professionnel de l’informatique, tu dois écrire de la doc.

Et donc, tu as des outils qui se sont imposés avec le temps pour pallier à ça. Tu as certains outils, je pense aux outils d’automation, par exemple, qui, certains, te permettent de documenter dans tes workflows d’automation, tu documentes des parties, tu fais en gros ce que tu faisais avant en code avec. Et tu as des outils comme certains outils de front, par exemple, où là, il n’y a rien. Donc, tu dois documenter d’une autre manière. Et donc, tu as tout un écosystème qui s’est monté autour de ça. Là, par exemple, tu parlais de JIRA. C’est intéressant parce que dans le milieu du no-code et des startups dans lesquelles je suis plutôt, l’outil de base pour documenter c’est Notion, qui est en gros un outil qui peut tout faire. Ça te fait des bases de données, ça te fait ta base de connaissances, ça te fait ton ticketing, ça te fait tout. Tout ce que je faisais avant avec des outils de ticketing, tu le fais dans Notion, alors moins bien et certainement moins optimisé, mais tu peux tout lier, c’est impressionnant. C’est une autre manière de faire. Tu as devant toi un outil où écrire de la doc, ça devient un process, une fois que tu as compris comment ça marche hyper simple et tu peux hyper structurer, tu as plein de templates et tout, c’est vraiment assez intéressant.

Et à côté de ça, tous les trucs que tu ne peux pas documenter, que tu pouvais faire dans le code sur tout ce qui est gestion de dépendances, test de régression, ce genre de truc, avec du no-code, soit tu ne le fais pas, soit tu as des nouveaux outils qui se créent. Et il y a un outil en particulier, par exemple, que j’utilise beaucoup et avec qui je suis plutôt proche de l’équipe de développement qui s’appelle ncScale. C’est des Français qui font ça et c’est un outil qui permet justement de faire un peu ce que je faisais avant avec mes outils ITSM, c’est-à-dire de l’inventaire automatisé, de la gestion de dépendances, ce genre de truc autour des outils no-code, c’est vachement intéressant, et de la documentation. Et donc en fait ces nouvelles formes de documentation où finalement, tu n’as plus de code, donc tu ne peux plus documenter dans le code comme toi, tu as l’habitude de faire.

Fabrice : Notion, c’est un peu comme un wiki, c’est ça ?

Walid : Notion, c’est à la fois un wiki, c’est à la fois une base de données. Malheureusement, ce n’est pas un outil libre, et dont l’interface utilisateur est vraiment extrêmement pensée et extrêmement logique, qui permet de tout lier. Pour en parler à d’autres gens, ils me disaient : en gros, c’est juste JIRA avec une super interface.

Fabrice : JIRA ou Confluence ?

Walid : Confluence, pardon.

Fabrice : par exemple, si c’est comme Confluence, ce qui manque dans Confluence, c’est qu’il n’y a pas de processus de validation du changement. Je pense que la chose pour quoi on utilise Git et qui est la plus importante, c’est la review. C’est la pull request, la review et donc la validation du changement. C’est-à-dire que tu veux changer quelque chose et il va y avoir cinq personnes qui vont lire le changement et qui vont dire : OK, c’est bon. Il y a cette idée que ce n’est pas : tu changes, tu publies et puis après, si ce n’est pas bon, on rechange. C’est : tu proposes un changement, on vérifie et une fois que c’est accepté, on est sûr que tout va bien. Moi, j’ai beaucoup utilisé Confluence pour des procédures internes sur de la documentation qui n’a pas besoin de validation, qui n’a pas besoin de passer par un workflow de validation. Et donc, pour ça, un outil, un wiki, Confluence, whatever, Drupal, tout système qui permet d’écrire quelque chose et de le publier, tout est bon. Il y a des préférences de gens. Il y a ce qui marche mieux, ce qui est le plus proche du reste de ce que tu fais, mais tout est bon.

Ce qui fait la différence, c’est à partir du moment où tu veux introduire un processus de validation.

Pour les release notes, on a commencé à introduire le fait que dans chaque ticket JIRA, on a un field qui est avec le contenu des release notes. Ça fonctionnait bien tant qu’écrire le contenu et le valider était fait d’un jet par la même personne. Je lis ce qu’il y a dans le ticket, où souvent, c’était des tickets qu’on copiait d’ailleurs. Ok, voilà. Et j’écris et je fais ma phrase et c’est fait. Et je n’y pense pas cinq minutes de temps. On a passé ça ensuite à des utilisateurs qui étaient plus juniors et du coup, il y a eu besoin de validation. C’est devenu une usine à gaz parce qu’on a dû rajouter un champ pour dire : draft, c’est une review, c’est validé, c’est OK. Mais par contre, on utilise un champ de JIRA qui est un champ qui n’a pas d’historique. Donc, on peut regarder les logs des changements, mais ce n’est pas un truc qui est fait pour ça.

Walid : je ne suis pas le plus grand spécialiste de Notion, mais je ne suis pas sûr que tu aies ce genre de notion de workflow de validation.

Fabrice : la documentation interne et la documentation du produit que tu as construit pour les utilisateurs, c’est deux trucs différents. Je pense que les Technical Writers, typiquement, ils sont plus là pour aller faire ta documentation face client. La documentation interne, tu as besoin d’introduire des processus de validation à un moment où l’équipe grandit. Surtout, les degrés de séniorité changent. Il faut que la personne qui est plus junior, elle puisse changer des trucs et savoir qu’il y a quelqu’un qui va revoir derrière et ça permet de se lancer. Moi, j’ai trouvé une application que j’aime beaucoup, qui s’appelle Obsidian. Obsidian, c’est ça, c’est une base de connaissances. C’est fait en Markdown avec les deux, trois extensions de Markdown qui font que tu peux faire des liens et des include entre les fichiers. Donc c’est parfait, c’est super. Une des extensions, c’est de pouvoir mettre le contenu dans Git. Ça permet deux choses. La première chose, c’est que ça permet d’avoir un historique, c’est-à-dire de voir ce qui s’est passé avant. Et la deuxième chose, ça permet d’avoir le même contenu sur ton téléphone et sur ton ordi et de passer le contenu de l’un à l’autre sans passer par une plateforme ou par un autre truc.

C’est un repository Git. Ça introduit la notion de historique, pas vraiment la notion de validation, mais la notion d’historique dans de la doc et tu peux voir quand ça a changé. Je sais que j’utilise de plus en plus comme mesure d’hygiène personnelle. Qu’est-ce que j’ai fait ces jours-ci ?

Impact de l’Intelligence Artificielle

Walid : avant qu’on raccroche le micro, un sujet que je ne peux pas ne pas aborder, c’est l’arrivée de l’intelligence artificielle et de l’impact que ça va avoir sur certaines des publications et votre boulot. Est-ce que tu as déjà des idées ou est-ce que tu vois déjà des choses qui étaient avant faites par des humains et qui maintenant sont faites par de l’intelligence artificielle ?

Fabrice : je trouve ça fascinant. Je pense que ce qui va arriver, on a du mal à mesurer. J’ai vu des gens qui s’amusaient à faire des punchlines pour des campagnes de marketing qui demandaient à un IA de leur générer les punchlines et ça marchait super bien. C’est une des caractéristiques de ce truc-là, c’est que tu peux lui dire : voilà, j’ai fait un drap tout pourri, est-ce que tu peux me rendre compatible avec la Bible de comment on écrit ? Et si tu as bien entraîné ton modèle, ça va le faire. Quand tu écris de la docs dans des uncharted waters, quand tu es sur un truc tout nouveau où l’intelligence artificielle, elle n’a pas grand-chose à se mettre sous la dent, c’est un perroquet il a besoin de contenu existant, donc, quand tu écris sur quelque chose qui est fondamentalement nouveau, l’intelligence artificielle, au moins pour le moment, elle n’a pas grand-chose à trouver. J’essaie de me dire ça le soir pour qu’on m’endormir. Après sinon, je vois comment, par exemple, le projet Ansible a été utilisé sur un projet qui s’appelle LightSpeed. Ce n’est pas documenter le code, c’est écrire le code à partir de la documentation.

C’est-à-dire que je veux faire une tâche qui fait ça, donc on l’écrit en langage naturel : installe-moi un serveur, installe-moi ce package et l’outil va rédiger le code du playbook Ansible à la place de l’utilisateur. Donc, pour l’instant, on écrit le langage naturel et ça va écrire le code. On a cette partie-là qui se met en place et qui demande encore le contrôle humain. C’est juste un template qui facilite le travail. Le boulot des Tech Writers qui est l’inverse, c’est à partir du code, décris ce que tu veux. À ce moment-là, il faut que l’IA ait un ticket ou un brief pour le code qui soit super bien fait. C’est ça ? C’est rarement le cas. Ou un moyen d’aller découvrir aussi bien qu’un être humain pourquoi je veux faire ça et comment je vais le faire, puisque c’est ça, il faut trouver les deux trucs. Pour l’instant, je ne sais pas. Moi, je pensais il y a quelques années que quand on aurait s’est tout automatisé, il faudrait encore documenter l’automatisation et que c’était une bonne idée d’aller faire de la doc.

Walid : tu peux déjà demander à ChatGPT de t’écrire le texte de tes pull requests.

Fabrice : ça, si le Technical Writer, son rôle, c’est juste de faire ça, ce n’est pas un métier d’avenir. Surtout, je pense que ça va changer la manière dont les gens consomment de la doc. Ça ne fait pas vraiment de sens de se dire : je vais continuer à écrire de la documentation si les gens, ils ne vont plus lire de la documentation. Si les gens, ils vont poser des questions à un autre. Le boulot des writers, ça va être de produire du contenu que l’intelligence artificielle va ingérer et qui va être utile à l’intelligence artificielle. Je pense que pour que ça marche bien, il faut que ce soit du contenu qui soit encore plus formaté, qui ait encore plus de métadonnées. Parce que je pense que le contenu brut ne sert pas à grand-chose. Pour l’instant, il y a quand même des gens qui rajoutent des métadonnées sur du contenu. Ça va se déplacer peut-être par là, les gens qui sont plus language-bound, ils vont plus se déplacer vers produire du contenu brut pour nourrir la machine. Mais je ne sais pas ce que ça va donner. Vers quoi on va, je ne sais pas trop.

Tribune libre

Walid : pour finir, j’ai une traditionnelle tribune libre. Donc à toi la parole.

Fabrice : faites Le logiciel libre, les gens, c’est bien ! Contribuez au logiciel libre. Je ne sais pas si je suis vraiment un vieux con à dire ça ou quoi. J’ai l’impression que ce n’est plus les mêmes attentes pour les plus jeunes générations. Je ne sais pas si Linux va finir par être plus que pour les serveurs et plus du tout autre part, par exemple. Je me pose cette question. Je me demande : ce sera quoi la nouvelle révolution dans cinq ans ? Puisque de toute façon, c’est tous les cinq ans que tout change. C’est quand même intéressant ce monde où tout change très vite.

Walid : C’est le mot de la fin. Merci Fabrice d’avoir pris du temps pour parler de ces sujets autour de la documentation. Je pense que si ça vous a plu, bien entendu, n’hésitez pas à le partager sur les réseaux sociaux et à en parler autour de vous. À bientôt.

Cet épisode a été enregistré le 3 mai 2023.

Transcription par Raphaël Semeteys

Pour en savoir plus

Licence 

Ce podcast est publié sous la double licence Art Libre 1.3 ou ultérieure – CC BY-SA 2.0 ou ultérieure.

Laisser un commentaire