Pas un jour ne passe sans qu’un nouvel outil, service, langage de programmation ou une nouvelle version d’une bibliothèque logicielle ne voie le jour. Il est facile de se sentir dépassé. Ce qui complique encore davantage cette technosphère en perpétuelle mutation, c’est bien souvent l’absence ou l’insuffisance de documentation. Un contenu bien documenté facilite pourtant l’appropriation des solutions, tant pour les utilisateurs que pour les contributeurs. À l’inverse, une solution mal documentée peine à toucher son public cible. Il faut dire qu’il est difficile de fournir une documentation claire et complète pour chaque technologie. Et dans le cas des petits projets, la documentation semble souvent écrite par des développeurs, pour des développeurs.
Comment bien documenter une solution ? Comment attirer l’attention de nouveaux utilisateurs ou contributeurs ? Comment maintenir cette documentation à jour ? Il faut parfois faire des choix, réduire les options disponibles dans un logiciel, en simplifier l’usage et proposer une interface minimaliste à l’utilisateur final. Une telle approche limite le besoin de documentation spécifique à l’interface. Prenons l’exemple des moteurs de recherche : leur interface épurée facilite l’usage quotidien. Les options avancées, comme les filtres, sont pensées pour les utilisateurs avertis. À l’inverse, dans les interfaces plus simples, l’introduction de nouvelles options peut rebuter les utilisateurs. Il faut donc trouver un équilibre entre simplicité et richesse fonctionnelle.
À mesure que les logiciels ou services web évoluent, on observe une tendance à ajouter toujours plus d’options, à repenser les menus… Or, les utilisateurs finaux peinent souvent à suivre ces changements, même mineurs. Un simple déplacement de bouton, anodin pour un développeur, peut perturber les repères d’un utilisateur habitué à une certaine routine. Pour lui, il faudra alors réapprendre à localiser les fonctionnalités.
C’est là que les guides pratiques prennent tout leur sens. Les entreprises qui en ont les moyens publient des « FAQ » (foires aux questions) pour répondre aux interrogations fréquentes sur leurs produits. Mais ces contenus sont bien souvent limités à quelques langues, principalement l’anglais. Et quand un produit vise un public international, il faut faire appel à de nombreux traducteurs. Comme évoqué plus haut, cela devient vite un casse-tête dès lors que le logiciel évolue rapidement : les documents traduits se retrouvent obsolètes en un rien de temps.
Des efforts ont été faits pour automatiser la génération de documentation. On produit ainsi automatiquement des pages statiques ou dynamiques pour les interfaces de programmation (API) ou les kits de développement logiciel (SDK). Les pages statiques sont généralement bien indexées par les moteurs de recherche, contrairement aux pages dynamiques, qui ne le sont que par quelques-uns. Pour des produits ou API de grande envergure, les pages dynamiques permettent de couvrir un large éventail d’options. Mais il reste recommandé de générer régulièrement des pages statiques à partir de celles-ci.
La documentation automatique ne prend pas encore en compte l’interface utilisateur finale (le « front-end »). Il est grand temps que les développeurs mesurent l’importance de relier les éléments de l’interface utilisateur au code, afin que les guides pratiques et les FAQ reflètent fidèlement chaque petite modification. Les utilisateurs ne devraient pas avoir à fouiller pour retrouver une fonctionnalité après une mise à jour.