Documentation technique : ne sous estimez pas son importance – Hubert Sablonnière

Importance de la documentation technique - Hubert Sabonnière

Peu de personnes s’intéressent à la problématique de la documentation technique avec autant de sérieux et d’énergie que Hubert Sablonnière. Les Sfeiriens Ludovic Borie et Romain Lespinasse lui ont demandé d’expliquer sa vision sur le sujet et de présenter les outils à connaître actuellement.

SFEIR : Bonjour, peux-tu te présenter ?

Hubert Sablonnière : Bonjour, je m’appelle Hubert Sablonnière, je suis développeur Web et je travaille chez OpenDevise. Nous aidons des éditeurs de logiciel à améliorer la manière dont ils créent, gèrent et collaborent sur leurs contenus pédagogiques. Par cela, j’entends leur documentation, formations, présentations… On essaye, à travers des pratiques et différents outils sur lesquels on travaille, notamment Asciidoctor, de pousser les gens à considérer que leur documentation technique doit être traitée comme du code et mérite la même attention. On parle alors du fameux « Documentation as Code ».

Un des enjeux est de rendre sa documentation technique attractive, autant sur la production qu’au moment de la lecture : comment s’y prendre ?

Il y a deux parties dans ta question.

Concernant la rédaction de contenus, plusieurs membres de la communauté travaillent sur des plug-ins pour l’éditeur Atom. Certains sont directement liés à l’édition de contenus AsciiDoc, pour avoir un live-preview ou la coloration syntaxique par exemple. Ensuite on va utiliser d’autres plug-ins qui sont plus généralement liés à l’écriture. Je pense notamment à zen ou clean qui épurent l’interface pour se focaliser uniquement sur les contenus.

Chez OpenDevise, on a aussi pas mal d’astuces et de conseils pour aider les rédacteurs à mieux écrire. Sur ce sujet, je vous conseille deux présentations de mon collègue Dan Allen1 & 2.

Sur la partie lecture de la documentation technique, on applique les mêmes bonnes pratiques que sur n’importe quel site Web où il y a du contenu. Il faut soigner le contraste, la taille du texte, les performances de chargement qui sont souvent négligées, alors que déterminantes dans l’expérience de lecture. Il reste beaucoup d’expérimentations techniques et non techniques à creuser sur ce sujet. On réfléchit aussi au concept de « Offline first », sujet que j’aime beaucoup, sur la doc. Allez voir du côté de Devdocs ou Lodash, ils font des choses sympas là dessus.

Tu as parlé de « Documentation as Code ». On est dans une mouvance du « tout as code », comme le « build as code », est-ce que tu penses que ça change quelque chose pour le développeur dans sa vie de tous les jours ?

Pendant des années, on a répété aux développeurs qu’ils devaient faire des tests unitaires pour améliorer la qualité de leur produit. Aujourd’hui, on essaye de les convaincre qu’une bonne documentation technique est aussi un vrai gage de qualité. En gérant sa doc comme son code, on va pouvoir la versionner, la tester, la valider et l’intégrer à l’usine de build pour la publication. Ainsi, on évite aux développeurs d’ouvrir Word ou d’utiliser un Wiki. À la place, on les laisse simplement utiliser leur environnement de développement de tous les jours.

Mais faut-il être développeur pour produire de la documentation technique ?

C’est toute la question. Chez OpenDevise, on a une collègue qui est auteur de romans et qui a été éditrice. Elle n’a pas du tout de formation technique. Forcément, on essaye de la convertir à tous ces outils, mais c’est difficile. Cela dit, quand on s’intéresse au monde de l’édition, on se rend compte que les problématiques sont les mêmes. Faire des brouillons, différentes versions d’un même document, ce sont des choses que les développeurs font aussi, et ça parle à tout le monde. La différence, c’est le vocabulaire et les outils, mais les pratiques derrières sont à peu près les mêmes.

Comment gérer la transition entre la documentation technique dite classique et la documentation « as code » ?

C’est vraiment le cas de figure où l’on intervient beaucoup : des migrations vers du « Doc as Code » avec asciidoctor. Tout d’abord, il existe des outils comme Pandoc qui vont faciliter la migration d’un format à un autre. Mais une migration comme celle-là, c’est aussi l’occasion d’effectuer une vraie conduite du changement au sein des équipes, et en profiter pour modifier leurs habitudes, leur apprendre à collaborer différemment, avec des Pull Requests par exemple.

Il y aura aussi une grosse charge de travail sur le redécoupage et la réorganisation de la documentation technique. Où la stocker, doit-on répartir cela en plusieurs repositories ? La doc doit-elle être au même endroit que le code ? Il faut aussi réfléchir au versionning… C’est un travail qui prend du temps pour trouver la formule qui correspond le mieux au projet et au contexte.

Vous développez asciidoctor, peux-tu présenter cet outil ?

Il y a quelques années, Dan Allen a co-créé asciidoctor. C’est un compilateur du langage de markup AsciiDoc, codé en Ruby. La grande force d’asciidoctor, c’est le nombre de formats d’output disponibles et les extensions. Asciidoctor jouit également d’un écosystème comportant beaucoup de contributeurs et d’outils complémentaires. Il existe des adaptations pour différents écosystèmes : asciidoctorJ dans la JVM ou encore asciidoctor.js pour les navigateurs ou Node. Des entreprises comme Ninja Squad écrivent des livres entiers avec asciidoctor, il faut vraiment appréhender la liberté que cela offre.

En ce moment, on réfléchit beaucoup sur ce qui touche aux présentations. Finalement, en ne rédigeant qu’une fois, en préparant des images, des diagrammes et de la prose, est-ce que je ne peux pas générer à la fois un article dans plusieurs formes, une forme longue qui ira sur le blog, une forme courte et aussi générer les slides avec ? La question est : comment rapprocher le texte écrit du discours oral qui va avec la présentation ? Nous prônons beaucoup l’arrêt du couplage fond et forme. Avec AsciiDoc et le concept de « rôles », cela devient plus facile d’ajouter de la sémantique métier à notre contenu. Un rôle donné sera peut-être mis en valeur par une classe CSS dans le HTML, mais peut-être que dans l’ebook ou le PDF, on lui attribuera une couleur ou une mise en forme différente ?

Tu as fait beaucoup de conférences ces derniers temps, quels sont les outils que tu utilises pour préparer tes présentations ?

Depuis quelques temps, on travaille beaucoup sur bespokejs. L’avantage de cet outil est sa modularité. Par exemple, les slides qui défilent avec le clavier c’est un plug-in, les listes à puce c’est un autre plug-in. Nous travaillons donc sur un ensemble de plug-ins qui nous manquent, et qui nous permettraient de présenter nos talks comme on le désire. Typiquement, on sait que quand on présente du code, on doit le présenter sous forme d’histoire et pouvoir afficher chaque ligne dans un ordre bien précis. D’ailleurs, ce code, peut-être voudrait-on qu’il soit exécutable, testable ? On veut aussi pouvoir décrire son speech, mettre des indications sur le débit de parole, le positionnement sur scène…

Pour résumer, mon conseil c’est de travailler avant tout sur le contenu : on doit raconter une histoire, avoir un fil conducteur. Il faut décoréler ça de la mise en forme, qui elle doit éviter toute complexité cognitive pour ne pas perdre la personne qui vous regarde.

Merci à Hubert Sablonnière pour ses réponses !

Vous aimerez aussi...