Une fonctionnalité non documentée n'existe pas

J’écris ces lignes peu après que Snowflake a annoncé qu’il avait licencié 70 personnes chargées de la rédaction technique sous prétexte que l’IA peut faire leur travail.

Comme je l’ai exprimé sur LinkedIn :

C’est définitivement l’une des pires idées possibles. L’IA doit être nourrie de contexte solide pour produire des réponses adéquates. Seuls les humains peuvent produire ce contexte. Et la documentation est précisément ça.

Cela m’a poussé à écrire sur une bonne pratique adoptée dans toutes les équipes avec lesquelles j’ai travaillé, à Traveldoo, SensioLabs, Blackfire, Upsun et Bump.sh, résumée simplement : une fonctionnalité non documentée n’existe pas.

La documentation comme référence utilisateur

Il y a de bonnes chances que parmi les lecteurs de cet article, la plupart connaissent l’acronyme RTFM.

Permettez-moi de vous le rappeler :

• Read (Lisez)
• The (le)
• Vous savez, ce mot qui commence par un F, et se termine par outu
• Manual (Manuel)

Comment pouvez-vous jamais cracher ça au visage d’un utilisateur de la façon la plus passive-agressive possible, si le foutu manuel n’existe pas ?

Par introspection, croyez-vous vraiment que chacune de vos fonctionnalités est auto-découvrable ? C’est-à-dire que n’importe qui dans le monde (même si réduit à votre base d’utilisateurs) aura le même cheminement de pensée que le vôtre en naviguant dans votre application ?

Soyons honnêtes : même les plus grands noms du SaaS dans le monde n’offrent pas la même UX pour des fonctionnalités similaires. Avez-vous déjà essayé de retrouver votre dernière facture d’abonnement SaaS ? Presque aussi difficile que de comprendre comment fonctionne un four à micro-ondes avec plus d’un seul bouton.

La documentation est comme une carte. Quand vous êtes perdu, il y a un endroit qui décrit précisément ce que vous pouvez faire et comment le faire. Et quand cette documentation est bien rédigée, vous pourriez même y trouver une description de “pourquoi cette fonctionnalité est-elle même intéressante”.

Si votre utilisateur ne peut pas trouver une fonctionnalité donnée, ou comprendre comment l’utiliser, peu importe l’effort que votre designer y a mis, c’est comme si elle n’existait pas.

La documentation comme marketing

Savez-vous l’un des points forts de Symfony, le projet Open Source PHP ? Spoiler : la documentation. Et c’est le cas depuis ses tout débuts.

Une documentation solide et approfondie, dans le monde SaaS et encore plus dans le monde des outils pour développeurs, est essentielle à l’adoption. Et elle est essentielle à l’acquisition aussi, que ce soit pour des considérations basiques comme le SEO, ou des plus élevées comme le positionnement. Plus la documentation est propre, profonde et bien découvrable, plus le produit est professionnel.

La documentation comme nourriture pour l’IA

Travailler chez Bump.sh, une plateforme de documentation d’API, a amené ma perception de la documentation à un tout autre niveau.

Depuis plus d’un an que nous parlons de MCP. Même s’il est encore imparfait, tout l’intérêt du MCP est de permettre aux agents IA d’interagir directement avec les APIs, basé sur leur description technique complète. Autrement dit : la “documentation”.

Cela fait aussi plus d’un an que toute une variété d’outils, comme Kapa.ai, construisent des agents support et des fonctionnalités qui se nourrissent de la documentation pour fournir cette interface en langage naturel pour aider les utilisateurs.

Dans l’espace des APIs, il y a un actif stratégique clé : les spécifications, comme OpenAPI. Même si les pratiques de rédaction de telles documentations varient (certains la génèrent encore à partir du code, tandis que les meilleures pratiques montrent que la voie royale est de l’écrire avant le code), elles existent pour un seul but : fournir la description exacte de la façon dont une API est construite et comment les humains et les machines peuvent interagir avec elle. Au point que beaucoup la voient comme un contrat, un accord signé entre les parties sur la façon dont elles devraient interagir au niveau programmatique.

Ça apporte de la structure et de la sémantique. Avec la profondeur et l’exhaustivité, c’est la base la plus solide que vous puissiez donner à une IA. Et à propos de l’IA générant des docs, dans cet espace c’est une pratique depuis des années de générer des fichiers OpenAPI à partir de scripts de code (sans IA nécessaire car c’est complètement déterministe). Ça fonctionne bien avec quelques endpoints et verbes. C’est horrible dès que la complexité de l’API augmente, et très vite complètement inutile.

En fait, ça fait un moment que je regrette qu’il n’existe pas un tel standard pour le reste des docs produit. Serait-ce une combinaison de graphes de connaissances, de consensus sur les modèles d’interaction utilisateur et les types de fonctionnalités, soutenue par un langage de description adéquat ? C’est peut-être la raison pour laquelle c’est si complexe à construire et pourquoi ça n’existe pas. Pourtant tout le marché aurait beaucoup à y gagner.

Méthode de documentation produit

Une approche qui ne règle pas tout, mais que je peux quand même recommander : Diataxis.

Elle fait une distinction claire entre le contenu qui aide les personnes à apprendre et ceux qui les aident à faire, qui responsabilise les personnes à découvrir et qui responsabilise le produit à construire l’adoption.

Suivre cette approche aide à construire :

• Des tutoriels
• Des guides pratiques
• Des explications
• Des docs de référence

Livraison produit et documentation

Laissez-moi mettre un peu d’agilité dans l’histoire. Avez-vous déjà entendu parler de la “Définition de Terminé” ? Inutile d’être un extrémiste Scrum. C’est du pur pragmatisme. Il s’agit d’avoir une checklist pour déterminer si votre fonctionnalité est prête à être mise en production.

Oui, les docs devraient être sur cette checklist. Oui, j’entends par là à la fois les docs internes que seuls les développeurs produit lisent ET les docs utilisateurs.

Et dans notre monde, elles devraient même faire partie du code poussé vers les environnements de test et de staging, car dès que vous utiliserez un agent pour effectuer des tâches de pré-production, cette documentation lui donnera un contexte critique.

ÉCRIRE LE FOUTU MANUEL

J’ai récemment vu un post LinkedIn d’une interprète expliquant pourquoi son travail sera toujours essentiel, malgré l’IA, à travers un exemple spécifique : la traduction des noms de Harry Potter. Il ne s’agit pas seulement d’avoir quelque chose qui permet un doublage décent pour les arts du mouvement ou la compréhension à la lecture. Il s’agit de ce que les mots transmettent dans la façon dont ils sont prononcés. Il s’agit des émotions qu’ils génèrent pour nous, humains.

Oui, une IA fera une traduction décente. Mais elle manquera inévitablement l’art du raffinement. Elle peut tomber à plat, ou être à des lieues de ce que l’auteur voulait dire.

Maintenant imaginez une IA lisant du code pour générer un ensemble complet de documentation Diataxis. Elle remplira les pages, sans aucun doute. Mais alors, ne me dites pas de LIRE LE FOUTU MANUEL si vous ne l’ÉCRIVEZ pas vous-même.

Image de une par Jonas Jacobsson.