Pour documenter l’interface d’une application, il est important d’écrire de façon claire et concise, mais ajouter des visuels (captures d’écran, diagrammes, vidéos, GIF, etc.) est essentiel pour ajouter du contexte et illustrer ses propos.
Mais ces visuels doivent être mis à jour en même temps que la documentation associée, et c’est depuis longtemps l’une des tâches les plus chronophages pour les rédacteurs. Logiquement, plus les visuels sont nombreux, plus ce processus prend du temps.
Ayant moi-même pu comparer un grand nombre de documentations différentes, je sais qu’il n’y a rien de plus frustrant que de suivre des instructions avec des icônes, des captures d’écran et d’autres éléments visuels puis de réaliser que ceux-ci ne s’appliquent plus à la version que j’utilise.
L’ensemble de la documentation Nuxeo contient environ 9 000 captures d’écran qui aident nos lecteurs à comprendre les concepts et les cas d’utilisation de notre plateforme de services de contenu. À chaque mise à jour de notre interface, un important travail de mise à jour nous attend afin de vérifier que les captures sont toujours d’actualité et qu’elles n’induiront pas nos lecteurs en erreur. Et je peux fièrement affirmer que notre interface et notre expérience utilisateur se sont considérablement améliorées au cours des dernières années !
Gestion des captures : Avant
Il y a encore quelques mois, nos captures d’écran étaient stockées dans notre référentiel de documentation GitHub et nous utilisions Git LFS pour gérer ces fichiers volumineux. À chaque changement impactant l’UI/UX (en général tous les trois mois, à chaque nouvelle version), nous devions mettre à jour toutes les captures d’écran, pour toutes les versions concernées et tous les types de documentations (technique, fonctionnelle, tutoriels, etc.). Si les captures étaient renommées, nous devions répercuter ces modifications dans l’ensemble de la documentation.
Après de nombreux lancements de produits, et de nombreuses heures perdues, nous avons décidé qu’il était temps d’optimiser notre processus de gestion des captures d’écran. Et quelle meilleure solution que la plateforme de services de contenu la plus moderne et la plus innovante du marché : la nôtre !
Gestion des captures : Après
Puisque la plupart des employés de Nuxeo collaborent sur notre documentation, nous souhaitions qu’elle soit facile à utiliser et à maintenir. Nous avons commencé par créer un type de document personnalisé dans Nuxeo Studio avec des attributs de métadonnées spécifiques (produit, version de la ressource, nature, description, etc.). Nous avons également créé une recherche spécifique pour ce type de document afin que les utilisateurs puissent vérifier rapidement si une capture doit être mise à jour.
Pour ce type de document, nous avons ajouté un script qui génère un identifiant unique pouvant être utilisé sur les pages de documentation associées. Voici le résultat :
{{!-- ### nx_assets ###
path: /default-domain/workspaces/Product Management/Documentation/Documentation Screenshots/Studio/NOS/Connect Application Edited
name: CONNECT-application-edited.png
studio_modeler#screenshot#up_to_date
--}}
La dernière étape a été de connecter notre plateforme au site de documentation, pour qu’à chaque redémarrage de notre build (planifié automatiquement chaque jour), celui-ci vérifie si les captures d’écran ont été mises à jour et, le cas échéant, signale les captures concernées.
Pour y parvenir, notre code récupère les métadonnées de chaque capture référencée dans la documentation et les éléments correspondants.
Et ensuite ?
La prochaine étape est de migrer les captures existantes vers notre plateforme puis de les convertir dans notre type de document personnalisé, le tout en continuant à améliorer le processus de récupération de ces ressources afin d’accélérer le build. Notre objectif est ainsi de récupérer un manifeste de toutes les ressources et de créer un lien direct vers l’espace de stockage de ces ressources dans S3.
Ensuite, nous allons continuer à exploiter le potentiel de la plateforme Nuxeo en matière de Digital Asset Management pour gérer les captures d’écran : redimensionnement automatisé, watermarks, contrôles qualité automatisés et alertes.
Notre site de documentation va prochainement accueillir de nouvelles fonctionnalités ! Et comme toujours, vos retours et vos commentaires sont les bienvenus !
Manon est Lead Technical Writer chez Nuxeo. Découvrez son parcours ici.