La documentation technique : une autre vitrine de l’entreprise
La documentation technique est un facteur de growth et de rétention client trop souvent oublié. Découvrons ensemble les bonnes pratiques et quelques outils utiles afin d’avoir une documentation de la même qualité que votre service client.
L’époque des logiciels on-premise mis en place dans le cadre d’un projet de 6 mois accompagné par des experts de l’éditeur du logiciel est révolue, nous sommes maintenant dans celle du SaaS avec des mises en place et des onboardings en une semaine. Mais pour autant, les logiciels sont devenus de plus en plus complexes avec de plus en plus d’offres techniques annexes.
Quel SaaS aujourd’hui ne propose pas à ses clients de faire les choses à sa manière en utilisant une API ?
Pour qui et pourquoi ?
Une affaire de développeurs
Au moment de la création d’une documentation technique, on fait trop souvent l’erreur de croire qu’elle n’a pas besoin d’être très soignée, car elle ne sera lue que par des développeurs aguerris : c’est faux !
Elle doit pouvoir être lue par tout le monde même si chacun aura son niveau de compréhension du sujet.
En effet, selon vos clients, la documentation technique sera peut-être étudiée par un commercial dans le cadre d’un appel d’offre, par un prospect lors de son comparatif des différents SaaS sur le marché, par un Product Manager ou même par un opérationnel.
Il est donc de votre responsabilité de faire en sorte que toutes ces typologies de personnes puissent non seulement trouver l’information technique qu’ils recherchent, mais surtout qu’ils n’en sortent pas traumatisés …
Je ne compte plus le nombre de fois où je me suis retrouvé face à une documentation technique si floue que je n’arrivais pas à lancer une simple requête d’API après l’avoir lue.
Un facteur de growth
La seconde erreur souvent commise est de croire que la documentation technique n’a aucun impact commercial.
Soigner sa landing page, la description de ses fonctionnalités, son pricing compétitif c’est bien : faire une documentation technique accessible, c’est mieux !
A l’aire du full SaaS, un prospect arrive avec des besoins en termes de fonctionnalités, des contraintes de prix mais aussi des exigences en termes d’intégration. Il voudra par exemple pouvoir se connecter en SSO, accéder à certaines informations depuis une application tierce ou même synchroniser son workflow avec le vôtre. Et pour avoir toutes ces informations, il va se tourner vers votre documentation technique…
Si celle-ci n’est pas assez friendly, alors il risque de ne même pas vous contacter, car il sera persuadé que ce sera trop compliqué de vous intégrer dans son écosystème.
C’est tout de même dommage de perdre des clients par ce qu’ils pensent ne pas pouvoir faire quelque chose qui est en fait possible et pas forcément compliqué !
Il ne faut pas oublier qu’une majorité de la clientèle des SaaS est constituée de TPE/PME ayant souvent des effectifs techniques limités. Il y a peu de chances que votre client ai une direction achat et encore moins un consultant technique pour ces sujets. Alors, plus votre documentation présentera simplement les possibles, plus vous rassurerez votre client en lui donnant l’impression d’une intégration smooth et painless.
Un facteur de rétention
L’avantage d’un SaaS pour le client, c’est qu’il peut partir quand il veut : il faut donc le retenir !
Deeper the merrier
Un client qui a réussi à vous intégrer dans son écosystème est un client qui ne churn pas : vous avez donc tout intérêt à faire en sorte que cette intégration soit la plus simple possible.
Certains clients vont vouloir s’intégrer dès l’onboarding et seront donc souvent très accompagnés et très habitué à solliciter les équipes CSM, mais pour beaucoup cette envie se fait un peu plus tard quand la communication est moins fréquente. C’est tout à fait normal, on va en général se laisser quelques mois d’utilisation avant d’engager des frais pour lancer des intégrations comme la mise en place d’une connexion SSO ou le développement d’un front utilisant les données de l’API.
Et c’est précisément dans cette période, où le client est satisfait et veut s’intégrer, qu’on peut le perdre s’il n’a pas moyen de réaliser cette intégration le plus simplement possible. Sur chaque marché, il y a de nombreux SaaS en concurrence et si votre client n’arrive pas à s’intégrer faute de documentation, il commencera sûrement à revenir voir ce que font vos concurrents.
Enfin, il ne faut jamais sous-estimer le pouvoir que peuvent avoir les équipes techniques. Si le CTO de votre client trouve la documentation illisible et n’a pas envie de perdre du temps à vous intégrer, vous pouvez être sûr que ça jouera en votre défaveur.
Dos & Don’ts
✅ Dos
- 🖥 Une UX user-friendly
L’expérience utilisateur est importante même pour une documentation technique : la navigation doit être simple, les différents sujets clairement différenciés, les points d’attention mis en avant. - ⁉️ Deux niveaux de langage
Comme expliqué précédemment, la documentation doit pouvoir être lue aussi bien par des opérationnels que par des développeurs. Elle doit donc aborder simplement les problèmes solutionnés tout en détaillant les actions techniques à réaliser. - 🧪 Des tests intégrés
La première chose qu’on a envie de faire lorsqu’on nous présente une requête ou un bloc de code, c’est de le tester : alors simplifiez ces tests en les intégrant à votre documentation. - 🔍 Clarté et simplicité
Même si elle n’est lue que par des personnes techniques, votre documentation doit être la plus simple possible.
- Il faut un token pour accéder à votre API : détaillez comment l’obtenir !
- Vous utilisez une méthode d’authentification peu ordinaire : détaillez-la !
- Cette requête utilise un paramètre comme un identifiant d’entreprise : expliquer où le trouver ! - 👥 Utilisez des personas
Les techniques de Product Management peuvent aussi s’appliquer à votre documentation technique : définissez les différents personas qui vont la lire, leurs attentes, le langage qu’ils utilisent…
Ainsi et en vous mettant à leur place, vous minimiserez la frustration côté client.
❌ Don’ts
- 🧑💻 Laisser la responsabilité aux développeurs
Bien sûr que ce sont les plus à même de pouvoir créer de la documentation technique, mais ils n’ont pas, en général, l’habitude d’adopter un niveaux de langage plus opérationnel. La gestion de la documentation par un PO/PM en coordination étroite avec les développeurs permet d’assurer d’avoir un bon niveau de langage, mais aussi un niveau de détail suffisant, le PO/PM apportant un regard extérieur sur le sujet. - 📋 Ne pas mettre d’exemple
Cela semble simple et pourtant, il existe encore des documentations ne fournissant pas d’exemple. Afin de vous montrer à quel point les exemples sont important, je vais prendre deux exemples :
- Un paramètre d’API peut très bien être dans le path, la query ou le body : sans exemples impossible de savoir et il faut alors tester toutes les solutions possibles…
- Un Iframe est l’une des choses les plus simple pour intégrer un SaaS à son site web, mais si vous n’êtes pas technique, un simple exemple peut vous faire gagner des heures. - 🥼 Ne pas fournir d’environnement de test
Comme dit plus haut, lorsque qu’on lit une documentation on a envie de tester et pour tester il nous faut : un environnement de test comprenant une API de test, mais aussi une interface. Ainsi, il est possible de tester la requête et de valider que les informations seront reprises correctement dans l’interface qui sera utilisée par les opérationnels. - 📄 Un PDF
Non, en 2022, il n’est plus acceptable que votre documentation technique soit un PDF, et ce, pour plusieurs raisons :
- Une documentation doit pouvoir être mise à jour quasiment en temps réel. À chaque changement sur votre API vous n’allez pas renvoyer le PDF à tous vos clients ?!
- Comme dit plus haut, une documentation doit donner des exemples permettre de tester le code et tout cela est compliqué par l’utilisation d’un PDF, puisque juste le fait de faire un copier-coller depuis un PDF peut parfois être une épreuve.
Expérience personnelle : Il n’y a rien de plus frustrant que de ne pas comprendre une documentation. J’ai un très bon niveau de compréhension technique notamment sur les sujets API et pourtant, il m’arrive fréquemment de ne pas comprendre certaines documentations, car il n’y a pas d’exemples, je ne sais pas avec quels credentials me connecter, etc. Et c’est en général le moment où je perds patience, abandonne le sujet pour ne le reprendre qu’une fois que quelqu’un a pu m’en expliquer le fonctionnement (ce qui décale souvent le sujet de plusieurs semaines).
Quelques solutions techniques
Maitenant que l’on sait comment faire une bonne documentation technique, découvrons quelques outils qui permettent de la faire simplement. J’ai choisi d‘en présenter trois, tous disponibles dans des versions gratuites.
Swagger
Swagger, c’est la référence Open Source pour documenter son API et si Swagger Editor qui permet de générer une documentation statique est très connu, leur outil Swagger UI l’est un peu moins.
Pourtant, il n’a que des avantages puisqu’il permet de mettre en ligne votre documentation API en affichant les différentes méthodes, les modèles de donnée, de mettre des exemples et de tester ces exemples en exécutant la requête directement depuis l’interface.
Si vous cherchez un outil simple, efficace et gratuit pour permettre à vos clients de comprendre facilement comment utiliser votre API et de la tester : c’est l’outil qu’il vous faut.
Postman
Postman, c’est l’outil qui permet de gérer de nombreuses API,de collaborer, de les tester mais aussi de les documenter grâce au Documentation Tool.
C’est déja un outil qui est très intéressant à avoir en interne pour gérer son API mais aussi toutes les API dont on est consommateur puisqu’il permet de rassembler au même endroits différentes APIs, différentes collections de méthodes, de gérer la partie environnements mais qui peut être encore plus intéressant pour la partie documentation.
En effet, même si l’UI de la documentation générée par Postman est très sobre, la possibilité de générer un bouton Run in Postman est très pratique.
En un clic, vous pouvez générer le code d’un bouton à ajouter sur votre site web qui permettra à vos clients de directement être redirigé vers Postman pour tester vos requêtes. Si avant ce bouton renvoyait vers une version statique de votre collection de requêtes, ce n’est plus le cas maintenant. La nouvelle version permettant à vos clients de forker votre collection pour pouvoir la tester tout en recevant toujours les mises à jour que vous aurez effectuées.
Docusaurus
Swagger UI et Postman sont de très bons outils pour documenter des API, mais ne permettent pas de documenter d’autres aspects techniques de votre produit comme par exemple la connexion SSO, vos Webhooks ou la manière de l’intégrer dans un site web via un Iframe.
Docusaurus, c’est un générateur de sites statiques en React-js qui est issu d’un projet open source de Facebook. Très simple à paramétrer, il vous permettra de générer un site avec une UI sobre et moderne pour documenter tous les aspect techniques de votre produit.
Facile à mettre en place et à déployer (sur Github Pages par exemple), il peut être rédigé presque uniquement en Markdown, donc est utilisable par des profils moins techniques. Même s’il demande plus de configuration et de développement que les deux autres outils, pour moi, c’est l’outil parfait pour construire une vraie vitrine technique de votre produit.
Un de ses avantages est aussi de rassembler une grosse communauté sur Github avec plus de 4000 pull request merged et certains plugins assez intéressants ont été développés comme Redocusaurus qui permet de générer automatiquement les pages pour chaque méthode de votre API à partir d’une spécification Open API.
Article écrit par Alexis Colonna.
Les avis exprimés sont les miens, n’engagent que moi et je ne m’exprime en aucun cas au nom de l’entreprise pour laquelle je travaille.
Que pensez-vous de cet article ?
Si cet article vous a intéressé, cliquez plein de fois sur 👏 pour me le faire savoir et partagez-le autour de vous. N’hésitez pas non plus à mettre vos remarques ou questions en commentaire.
