Quand la documentation technique devient un avantage business

Une discussion avec Pierre-Olivier Saint-Joanis,
Responsable Qualité pour HPS.

Comment la production de documentation était-elle historiquement organisée ?

Dans le passé, l’équipe documentation était constituée de 3 personnes, gérant un corpus documentaire de plusieurs centaines de documents. On distingue 3 audiences pour ces contenu. Tout d’abord à l’intention des utilisateurs des 14 solutions d’HPS: guides d’installation et de paramétrage, notes techniques, manuels utilisateurs, descriptions fonctionnelles. Ensuite à l’intention des développeurs : plusieurs centaines de fichiers décrivant la conception du logiciel, le modèle de données. Enfin à l’intention des décideurs de nos clients, les équipes Avant-Vente et Marketing d’HPS gèrent séparément la documentation PowerPoint.

Jusqu’à peu, nous produisions essentiellement des documents Word, transformés en PDF puis diffusés via Sharepoint. Ainsi, en se connectant à des sites Sharepoint, nos clients pouvaient y trouver à la fois de la documentation produit, et la documentation spécifique de leur projet – chaque mise en œuvre impliquant une part importante de personnalisation liée à l’activité du client, à la législation locale applicable, ou à l’interface avec son propre système.

Qu’est-ce qui vous a amené vers une approche de documentation structurée ?

Je suis responsable de la qualité, et la documentation a été intégrée récemment à mes attributions, avec comme objectif d’améliorer l’expérience utilisateur dans la recherche de l’information et du bon document. Un des principaux problèmes que nous avions identifiés, c’est que pour chacun de nos produits, il existe de nombreuses variantes dans le monde.

Ceci nous oblige à maintenir beaucoup de différentes versions de la même documentation. D’une part parce que le produit évolue et que tous les clients n’ont pas le même rythme de mise à jour de leurs logiciels. D’autre part parce que chaque client a des besoins spécifiques, et que ces derniers doivent bien entendu être documentés et mis à jour. Ainsi, on retrouve rapidement une dizaine de versions différentes d’un même document, pour le même logiciel.

Un autre sujet crucial est la notion d’audience. Un même sujet peut être traité sous un angle marketing ou avant-vente, sous un angle utilisateur – fonctionnellement, avec copies d’écran et manuel, ou encore sous un angle technique destiné aux ingénieurs chargés de la mise en œuvre ou de la maintenance du système. Cette pluralité d’audiences n’avait aucune solution élégante dans le système de documentation existant, nous obligeant à créer, dupliquer et donc à maintenir des types de documents différents et redondants, sans homogénéité, et sans possibilité de passer d’une audience à l’autre.

À propos de HPS

HPS est une multinationale, leader dans l’édition de solutions de paiement pour les émetteurs, acquéreurs, processeurs, opérateurs de réseaux mobiles, la distribution, ainsi que les switches nationaux et régionaux dans le monde.

PowerCARD, la suite logicielle d’HPS, couvre l’ensemble de la chaîne de valeur du paiement en permettant des paiements innovants grâce à sa plateforme ouverte qui permet le traitement de toutes les transactions initiées par tous les moyens de paiement, provenant de tous les canaux. PowerCARD est utilisé par plus de 400 institutions dans plus de 90 pays.

HPS est cotée à la Bourse de Casablanca depuis 2006 et possède des bureaux dans les principaux centres d’affaires (Afrique, Europe, Asie, Moyen-Orient).

https://www.hps-worldwide.com

Vous avez donc lancé un chantier de documentation structurée ?

Les besoins décrits précédemment s’accordaient parfaitement avec l’idée de la documentation structurée. J’ai alors décidé de monter un projet interne avec demande d’investissement dans des logiciels et des ressources qui nous permettraient d’atteindre l’objectif de passer de l’ère de l’artisanat à l’ère industrielle choisissant le modèle DITA pour l’écriture et la publication.

Le projet, de l’initiation au début de la réalisation a mûri pendant un an.

Comment avez-vous abordé le projet ?

Tout d’abord, il fallait préserver le « business as usual » : continuer de délivrer pour nos clients, maintenir l’existant. Nous avons donc évité, au début du moins, de tout changer. L’équipe de 3 personnes a continué à travailler avec leurs outils et techniques. Ils ont été bien entendu tenus au courant, consultés, impliqués. Et nous avons déployé une nouvelle équipe dédiée au chantier documentation structurée, qui a pu prendre ses marques sans perturber le fonctionnement de l’existant. Nous avons très fréquemment tenu l’autre équipe informée de la progression du projet, et dès le début nous nous étions engagés à les former à 100%. Maintenant l’intégration se passe bien, malgré un changement de culture radical. La logique de la documentation structurée est presque opposée à la logique d’écriture traditionnelle. Il faut vraiment toucher du doigt les avantages pour s’en persuader.

D’un point de vue organisationnel, nous avons abordé le sujet « par les deux bouts ». D’une part l’outillage de la rédaction, y compris la conversion du contenu existant, de Word vers DITA. Et d’autre part, en partant de l’expérience utilisateur : la définition des métadonnées, des taxonomies, des synonymes, des groupes et des permissions. C’est ainsi que nous avons pu mettre en place des procédures, par exemple créer une taxonomie pour la rendre homogène et exploitable par tous les utilisateurs.

Le tout s’est fait de manière très itérative, Nous confrontions très régulièrement nos avancées pour que les deux sujets convergent et se rejoignent. C’est ainsi que la taxonomie était enrichie, modifiée, normalisée. À chaque fois nous avons testé, publié, effacé, rajouté une source, etc. Cela s’est révélé être un facteur clé pour le succès du projet.

L’enrichissement de la taxonomie s’est révélé être un facteur clé pour le succès du projet.

Selon quels axes le contenu est-il organisé ?

Parmi les métadonnées utilisées pour organiser notre contenu, on retrouve la solution (parmi les 14 produits que nous offrons), le composant fonctionnel, et éventuellement un sous-ensemble du composant. Cette taxonomie permet à un article d’identifier directement le produit et le contexte dans lequel il est utilisé.

Nous utilisons également les métadonnées pour catégoriser chaque document selon son type : guide d’utilisation, documentation d’installation, support de formation, description fonctionnelle par exemple.

Par ailleurs, nous différencions la nature du document (structuré ou non structuré), l’auteur, la version du logiciel, la version du composant et du topic, la référence, ainsi que d’autres métadonnées comme l’audience cible.

Toutes ces métadonnées sont proposées comme filtres (facettes) pour les utilisateurs afin de préciser leurs recherches.

Enfin, pour répondre aux spécificités de chaque projet client, nous utilisons une dernière balise, en quelque sorte en amont de toutes les autres. Cette balise intitulée « Client » contient la valeur « Product » si le sujet s’applique à un produit et donc potentiellement à tous les clients, ou bien le nom du client s’il s’agit un document spécifique que seul le client nommé doit être à même d’accéder. Cette balise est essentielle dans notre système de droits d’accès.

Les outils utilisés

Componize est un CMS DITA qui optimise la rédaction, la gestion et la traduction de documentation à l’échelle de l’entreprise, et qui facilite la contribution des experts.

Fluid Topics capture tout le contenu technique, quel que soit son format, et délivre un portail de documentation dynamique, sans effort.

Componize et Fluid Topics sont intégrés pour faciliter la publication du contenu technique, sans perdre la richesse de cette structuration.

Comment votre nouvelle équipe a-t-elle pu avoir accès à l’expertise métier ?

Avec une équipe fraichement recrutée, cet accès était en effet essentiel. Nous avons effectivement intégré une rédactrice qui ne connaissait pas notre métier mais qui avait été formée à DITA. Elle a dû s’approprier 200 documents qu’elle a segmentés en topics, chargés dans notre CMS Componize, le tout sans maîtriser les sujets couverts par ces documents.

Elle a donc travaillé en binôme avec une référente métier issue de l’équipe existante à qui elle pouvait poser toute question. Ensemble, elles ont ainsi pu très largement factoriser les contenus, la documentation a d’ailleurs fondu d’un bon tiers. Puis elles ont défini des glossaires de définitions pour éviter les répétitions au sein d’un même topic de concepts récurrents, comme « compte », « carte », « marchand », etc. Nous sommes ainsi passés de 600 définitions réparties un peu partout à 90 définitions harmonisées, centralisées, homogènes et réutilisées.

La taxonomie métier a été réalisée en recensant dans un premier temps tous les mots clefs métier identifiés en parcourant les documents existants. Puis nous l’avons organisée en arborescence, avec synonymes, termes spécifiques, génériques. Cet outil s’avère très puissant pour la recherche dans Fluid Topics.

De quels contenus est constitué votre corpus documentaire ?

Le cœur de ce corpus est aujourd’hui essentiellement centré sur la documentation à l’intention de nos clients : réalisée en DITA avec Componize et publiée au travers de Fluid Topics, soit plus de 6500 topics.

Nous y ajoutons progressivement le contenu à l’intention des développeurs, qui est aujourd’hui stocké séparément, et les documents produits par HPS Academy (notre équipe de formation interne). À terme, nous envisageons d’y rajouter les supports d’avant-vente et les présentations marketing.

Pour les APIs, nous avons aujourd’hui un portail séparé et travaillons en parallèle sur une doc Swagger pour nos APIs JSON. Il faudra faire converger les 3 solutions.

L’équipe en charge des propositions commerciales pourrait aussi être intéressée dans un second temps.

  Faciliter la mise en œuvre

La documentation structurée avec DITA XML apporte de nombreux bénéfices, mais c’est un changement qu’il faut bien préparer. Il faut être particulièrement attentif aux notions de gestion du changement, et impliquer dès que possible les équipes concernées, rédacteurs et contributeurs. Le choix des outils est également important. Avec des interfaces simples et usuelles, le DITA CMS de Componize a contribué à l’adoption rapide des nouvelles pratiques.

Qui sont les utilisateurs de la documentation ?

Dans un premier temps, nous avons ouvert le portail à nos 300 ingénieurs internes. Le succès a été immédiat, en raison de la facilité qu’il apporte à cibler facilement la bonne information dans une masse importante. Les retours de ces utilisateurs sont excellents.

Nous avons ensuite offert l’accès à nos clients, qui peuvent chercher efficacement et avoir accès avec une efficacité et une simplicité incroyable au regard du volume et de la complexité de notre documentation. Ils peuvent exploiter toute la richesse fonctionnelle de Fluid Topics comme poster des remarques ou se constituer des Personal Books.

L’usage du contenu diffère suivant la phase du déploiement client. Ainsi, pendant la phase de setup qui dure de 6 mois à 2 ans, les clients ont besoin de tester, de comprendre le fonctionnement et comment le logiciel se paramètre. Ils vont utiliser les descriptions techniques, les guides utilisateurs, les fichiers d’interface. Ensuite, pendant l’exploitation qui durera 10 à 15 ans voire plus, les seuls documents qui seront consultés par les clients seront les guides utilisateurs – fréquemment au début, puis épisodiquement pendant la période de formation d’un nouvel opérateur.

Nous avons ouvert le portail à nos 300 ingénieurs internes. Le succès a été immédiat.

Quels changements ont pu s’appliquer sur la façon de produire le contenu ?

Au vu des premiers résultats, une équipe d’ingénieurs développeurs a été volontaire pour changer sa façon de produire la documentation du code. Ils ont compris ce que nous faisions, l’intérêt de DITA, des balises sémantiques. Ils ont choisi de produire leurs docs avec Componize et de les publier avec Fluid Topics. Une rédactrice se charge de la relecture et des éventuelles corrections (normalisation, choix des bonnes métadonnées).

Suite à ce pilote, nous avons organisé une présentation de la nouvelle plateforme à tous les ingénieurs, et d’autres équipes ont souhaité s’y mettre. Ça change assez radicalement la façon de produire la documentation puisque jusqu’à présent, les développeurs codaient, faisaient des démonstrations au profit des rédacteurs techniques qui produisaient alors la documentation en tout bout de chaine. Les développeurs n’écrivaient quant à eux que peu de contenu.

Notre objectif est d’augmenter la productivité et d’intégrer le développement de la documentation à la chaîne de production du code. Chaque segment de programme pourra être documenté au moment où il est écrit, par la personne qui le code. Si nous arrivons à faire changer les mentalités petit à petit en interne, ce sera une vraie disruption.

De la doc structurée au contenu

La méthode de construction d’une proposition commerciale s’apparente finalement à celle de la documentation structurée : beaucoup de copier/coller, d’adaptation aux spécificités du client, ce qui au final demande un énorme travail de fabrication et de personnalisation.

En adoptant les méthodes de la doc technique structurée, le gain de temps serait considérable. Nous regardons en particulier comment utiliser le concept de Personal Books de Fluid Topics pour agréger des sous-parties et aboutir à un document quasi-finalisé.

Cette nouvelle documentation, dans quelle mesure a-t-elle impacté le business ?

Un des impacts les plus forts a été la capacité à transformer la documentation en argument de vente. La version précédente de la documentation rassurait déjà le client car il pouvait voir que le logiciel existait vraiment pas uniquement sous forme de mockups, mais il devait recevoir la documentation par email (ou un extrait) et reporter à plus tard la réponse à certaines questions difficiles.

Quand un prospect demande une fonctionnalité, on sait maintenant lui dire « oui, on l’a et voilà comment ça marche », documentation à l’appui, instantanément. Avec Fluid Topics, il suffit à l’ingénieur avant-vente de taper quelques mots clef dans le moteur de recherche et on accède immédiatement à la réponse souhaitée. Les principaux articles qui parlent du sujet sont présentés, les facettes permettent de filtrer le produit concerné, sa version, c’est immédiat.

L’entreprise se dote ainsi d’une avant-vente augmentée, qui dispose de tout son savoir, plus tout ce qu’elle ne sait pas mais qui est présent dans la documentation. La documentation devient un élément clé du succès commercial de nos produits !

Quick facts

14 solutions logicielles
100+ développeurs sur les produits
200+ développeurs sur les projets clients
6 rédacteurs techniques
6500 topics

Visiter le site de HPS :
https://www.hps-worldwide.com

Lire cette étude de cas hors ligne ou l’imprimer ?

Télécharger

Estimer son retour sur investissement

Calculateur ROI en ligne