Des aides en ligne en HTML Help aux sites basés sur Markdown

Je fais de la documentation en ligne (Aide en ligne) depuis mes débuts, et en HTML depuis 2000. C’est une de mes spécialités.

Bien qu’il soit toujours possible de créer une aide en écrivant du HTML dans un éditeur de texte (ce que j’ai fait pour ma première Aide en HTML !), personne ne le fait. L’aide se doit d’être attractive et adaptable, c’est pourquoi après avoir beaucoup utilisé de HATs (Help Authoring Tools, outils de rédaction d’aide) j’utilise désormais une combinaison générateur de site statique/fichiers Markdown.

🔸 Fondamentaux pour la structure

Du HTML pur des premiers sites en HTML aux générateurs de sites Web statiques, les principes de base d’une documentation en ligne restent les mêmes.

Tout d’abord, la structure. Elle est toujours constituée de trois parties, héritées de l’époque où les cadres (frames) dominaient:

  1. Sur la gauche, la table des matières avec jusqu’à 2 sous-niveaux. Connue actuellement sous l’appellation “sidebar.
  2. En haut, le menu permettant de passer à une autre langue ou d’afficher des raccourcis. Il est toujours disponible sur les sites de documentation les plus récents.
  3. La frame principale, pour afficher le contenu. Commençant souvent par un sous-menu pour avoir un aperçu du contenu de la page et se terminant par différents liens du type «Voir aussi» ou «Précédent / Suivant». Maintenant, le sous-menu est en dehors de la page, mais toujours disponible dans le coin supérieur droit.

Une contribution essentielle de RoboHelp à la documentation en ligne a été de créer des sites Web d’aide, qu’ils soient compilés en un fichier unique .chm ou disponibles en tant que “webhelp” avec le traditionnel fichier index.html, disposant systématiquement d’un moteur de recherche, d’un menu que l’on pouvait développer ou réduire et d’un index.

🔸 Ils ont disparus (ou bientôt j’espère)

L’index, héritage de l’ère de la documentation imprimée, est la victime malheureuse des documentations modernes : cette fonctionnalité n’est plus disponible dans les générateurs de sites statiques. Mais qui aurait encore le temps d’en élaborer un manuellement? Vous, rédacteur technique, gardez certainement un souvenir mitigé de ce travail fastidieux qui consistait à pister chaque terme à ajouter à l’index…

Autre victime, les liens de type pop-ups (soulignés en pointillés verts) qui permettaient d’afficher une définition ou d’expliquer un acronyme. J’aimais bien ce type de lien.

Un mauvais usage que j’aimerais voir disparaître: ces grands tableaux fourre-tout, utilisés pour s’épargner la corvée d’écrire des phrases et/ou pour mettre en forme du contenu dans des pages HTML (ultime horreur, le tableau dans le tableau). Heureusement, Markdown ne permet pas ce type de mise en forme : smiley:

🔸 Fondamentaux pour le contenu

En ce qui concerne le contenu, une bonne aide est centrée sur les actions, structurée, avec des pages relativement courtes. Elle est facile à maintenir (mises à jours, gestion multilingue) et propose une navigation fluide (créée automatiquement par de nombreux générateurs de sites statiques). Elle contient un certain nombre de rubriques de base telles qu’un glossaire. Ces fondamentaux étaient déjà d’actualité il y a 20 ans.

⭐ Voici mes outils préférés pour créer de belles documentations en ligne !

  1. 🔗 Docusaurus v2
  2. 🔗 Hugo
  3. 🔗 Jekyll

Le present site web par exemple est une combinaison de fichiers Markdown et Yaml et d’un sympathique template Hugo. Des exemples de réalisation avec Docusaurus sont consultables dans mon 🔗 Portfolio.

J’ai beaucoup utilisé RoboHelp qui permettait de faire des aides en ligne en HTML avec moteur de recherche et index, et ce dès 1999. 🔗 Adobe RoboHelp est toujours une solution complète qui permet de personnaliser son design, de gérer le contenu et de générer une aide immersive consultable quel que soit l’appareil ou le format. Cependant, RoboHelp crée des fichiers en HTML et n’utilise pas Markdown.

Lisez cet autre article sur 🔗 Markdown.