Comment on a refondu la documentation Batch

Batch a mené ce début d’année un projet de refonte de sa documentation, qu’on peut dorénavant retrouver sur doc.batch.com.

C’est un projet transverse et pas aussi trivial qu’il n’y paraît. On a donc voulu prendre le temps de partager notre expérience pour aider de potentiels éditeurs de logiciels qui feraient face à un tel projet à faire les bons choix.

Cet article permet également à nos clients de comprendre les changements et bénéfices de cette évolution. Il prend la forme d’une interview de Selma, Solution Architect, qui a piloté ce projet.

Selma, pourquoi cette refonte ?

Deux raisons principales :

• La documentation Batch était éclatée entre deux endroits : doc.batch.com, qui contenait la documentation SDK, API, Dashboard et help.batch.com, notre Help Center, qui contenait des articles qui répondaient aux questionnements majeurs des clients sur tous les sujets. Ce n'était pas facile pour les clients de naviguer entre les deux. Nous servions à la fois des personas métier et des personas techniques avec notre documentation et ils ne savaient pas où aller. Il y avait aussi beaucoup de contenu répété dans les deux espaces.

• L’espace doc.batch.com était à éditer via Github directement. C’est une interface austère et assez lente quand il s’agissait de procéder à la publication. Elle n'encourageait pas les équipes à l’alimenter. L’espace help.batch.com était une interface Intercom Pages beaucoup plus facile à utiliser. Cette praticité a conduit beaucoup de production de contenu à se faire sous forme d’articles d’aide sur le Help Center. Un volume d’articles très important a été généré, créant des enjeux de maintenance.

Comment avez-vous commencé le projet ?

Nous avons mené une phase d’analyse des besoins en interviewant des clients, partenaires et utilisateurs internes en grand nombre. Cela nous a permis de ne pas être biaisés par les perceptions que nous pouvions avoir au départ. Nous avons également benchmarké la concurrence et des documentations que nous appréciions. Ça nous a donné une base de travail large pour poser une stratégie, et des KPI de succès.

Nous avons ensuite défini un rétroplanning des choses à faire, et créé une routine de sessions de travail régulières avec des référents des différentes équipes impliquées.

Nous avons également mis en place une façon de tenir informés les sponsors du projet par des points de synchronisation spécifiques.

Comment avez-vous structuré la documentation ?

Avant de choisir le bon outil, on a défini la structure de la documentation que nous souhaitions. Challenge majeur : nous avions à réunir sur un même portail des contenus très divers. Le choix s’est porté sur un framework connu en documentation, Diataxis (qui veut dire organisation en grec).

Cela nous a permis de structurer nos contenus en fonction :

• des objectifs des lecteurs :

  • faire ses premiers pas avec la section “Getting Started”,

  • débloquer un point précis et apprendre des choses avec la section “Guides & Best Practices”,

  • intégrer Batch à des solutions tierces avec la partie “Integrations”,

  • découvrir les dernières sorties de fonctionnalités avec la section “Release Notes”,

  • exploiter les APIs et SDKs avec la section “APIs & SDKs documentation”.

• de leur profil :

  • le nouvel utilisateur métier sera pointé vers “Getting Started”,

  • l’utilisateur expérimenté métier sera pointé vers “Guides & Best Practices”,

  • l’utilisateur tech sera pointé vers “APIs & SDKs documentation”.

Vous avez choisi un outil dédié, pourquoi ?

Nous avons défini les critères pour choisir le ou les outils qui nous permettaient de mettre en place notre vision.

Quelques critères clés :

• une simplicité d’usage car nos contributeurs sont de plein d’équipes différentes : CSM, Onboarding, Customer Care, PM, Tech, etc.

• des capacités de représenter la documentation API efficaces pour les personas techniques qui la consomment, avec notamment un besoin d’avoir Open API bien intégré.

• un seul endroit pour tout contenir, de la documentation technique à la documentation métier, en passant par les vidéos de présentation.

• une capacité à voir toutes les innovations produit dans une section Release Notes.

• des capacités collaboratives et de validation pas trop compliquées, mais tout de même présentes pour éviter d’avoir à collaborer hors de l’outil.

Différentes options s’ouvraient : exploiter un CMS, des framework open source, se baser sur des outils malléables types Notion, ou prendre un outil spécifique de documentation produit.

Sans rentrer dans les détails, nous avons privilégié une approche qui nous donnait le maximum de vélocité tout en répondant à nos critères clés, et notre budget bien évidemment.

Nous avons aussi considéré quelques éléments additionnels. Par exemple, l’outil que nous avons choisi, Gitbook, permet de consommer la nouvelle documentation centralisée de Batch comme on poserait une question à ChatGPT. Ces capacités AI permettent à nos clients d’être plus autonomes, en tirant partie de technologies GenAI très récentes. L’accompagnement a aussi été pris en compte et Gitbook a une présence européenne forte et réactive.

Quels sont les premiers résultats de cette migration ?

La nouvelle documentation centrale est sortie au premier trimestre 2025 et s’est largement enrichie sur le deuxième trimestre. On voit déjà des résultats tangibles.

Les utilisateurs internes sont très satisfaits des capacités de l’outil, à la fois simple et puissant. Cela se traduit par une propension à l’utiliser meilleure et une plus grande fraîcheur de données.

Les clients ont bien pris en main le moteur AI pour interroger la documentation, nous voyons les statistiques d’usages exploser. On apprend au passage beaucoup des requêtes faites.

C’est encore tôt pour mesurer la réalisation de nos KPIs plus long terme comme la baisse des demandes de premier niveau au support ou la disparition de clients qui nous indiquent avoir cherché dans la documentation une information mais pas trouvé de réponse.

Et pour la suite ?

Pour le projet documentation, il nous reste à fermer help.batch.com, qu’on a laissé quelque temps en transition. Cela arrivera fin juillet. Après cette date, des redirections assureront que les utilisateurs qui avaient mis en favoris les liens vers help.batch.com retombent sur des pages pertinentes sur doc.batch.com.

Mégane, Senior People Partner chez Batch, travaille maintenant à développer un Learning Management System (LMS), un prolongement de la documentation pour que nos clients et partenaires puissent se former à Batch en autonomie avec des contenus de haute qualité ! Ce sera l'occasion de revoir en profondeur notre programme de certification. On pourra revenir en parler plus tard.