Les fondamentaux de la doc en ligne
L’évolution des fichiers d’aide : des pop-ups et frames à la simplicité du Markdown
Je crée de l’aide en ligne depuis les débuts — à l’époque où HTML régnait et où les éditeurs étaient en essentiellement en texte brut. Beaucoup de choses ont changé, mais certains fondamentaux restent solides.
Dans cet article, je retrace l’évolution de l’aide en ligne, de RoboHelp et des structures en trois frames jusqu’à l’univers plus épuré du Markdown et des générateurs de sites statiques. Un mélange de nostalgie, de pragmatisme — et toujours dans l’objectif d’améliorer la documentation.
🟢 Je rédige et construis de la documentation en ligne (aide en ligne) depuis mes débuts, et je travaille en HTML depuis 2000. C’est l’une de mes spécialités.
Même si, techniquement, on peut encore créer de l’aide en écrivant du HTML dans un éditeur de texte (comme je l’ai vraiment fait pour ma toute première aide HTML !), plus personne ne fait ça aujourd’hui. Le contenu d’aide doit être attrayant et responsive — c’est pourquoi, après avoir utilisé de nombreux HATs (Help Authoring Tools), j’utilise désormais une combinaison de générateurs de sites statiques et de fichiers Markdown.
Fondamentaux de la structure
Du HTML pur des premiers sites d’aide aux générateurs de sites statiques actuels, les fondamentaux restent les mêmes.
La structure reste celle d’une mise en page en trois volets héritée de l’époque des frames :
- À gauche, la table des matières (TOC), avec jusqu’à deux niveaux de sous-pages. Aujourd’hui appelée “la sidebar”.
- En haut, le menu pour changer de langue ou accéder à des raccourcis — toujours utilisé dans la plupart des sites de documentation.
- Le volet principal affiche le contenu, généralement avec un sous-menu en haut de page pour une vue d’ensemble, et des liens "Voir aussi" ou "Précédent/Suivant" en bas. Ces sous-menus apparaissent désormais hors de la page, souvent en haut à droite.
RoboHelp a grandement contribué à la documentation en ligne en générant des sites d’aide soit empaquetés dans un fichier .chm unique, soit publiés en “WebHelp” avec une page d’accueil index.html. Les deux formats incluaient un moteur de recherche, des menus extensibles/réductibles et un index.
Ils ont disparu...
ou pour certains, on aimerait
L’index
L’index, hérité des documentations imprimées, a malheureusement disparu des sites d’aide modernes. Les générateurs de sites statiques ne le prennent pas en charge nativement, et qui a le temps d’en construire un manuellement ? Vous souvenez-vous, rédacteur technique, de la tâche fastidieuse consistant à suivre chaque terme à travers des dizaines de pages ?
Le lien pop-up
Autre fonctionnalité perdue : le lien pop-up, formaté avec des tirets verts, qui permettait d’afficher des définitions ou d’expliquer des acronymes en ligne. Je les adorais.
Bien qu’il soit théoriquement possible de recréer ce comportement en Markdown avec du HTML, ce n’est pas pris en charge nativement par Docusaurus. D’autres générateurs comme Hugo ou Jekyll peuvent proposer des tooltips via des plugins ou du HTML brut, selon le thème et la configuration.
Les grands tableaux
Un abus que j’aimerais voir disparaître complètement : les grands tableaux remplis de tout et n’importe quoi. Ils servaient à économiser des phrases ou à structurer la mise en page — souvent avec des tableaux imbriqués. Heureusement, Markdown ne permet pas ça. 😅
Fondamentaux du contenu
Un bon contenu d’aide est orienté action, bien structuré, et construit sur des pages courtes et lisibles. Il est facile à maintenir (pour les mises à jour et la gestion multilingue) et offre une navigation fluide — ce que de nombreux générateurs de sites statiques gèrent automatiquement. Il inclut aussi des éléments de base comme un glossaire.
Ces fondamentaux étaient déjà pertinents il y a 25 ans.
Outils préférés
Les sites ci-dessous m’inspirent — c’est pourquoi ils figurent dans mes favoris !
Mon précédent site (2019–2024), par exemple, a été réalisé avec un template Hugo, combinant des fichiers Markdown et YAML.
J’ai beaucoup utilisé RoboHelp, qui permettait dès 1999 de créer de l’aide en ligne en HTML avec moteur de recherche et index.
Adobe RoboHelp reste une solution puissante pour personnaliser les designs, gérer le contenu et créer une aide immersive et consultable sur tout type d’appareil ou de format.