Introduction
Il existe différentes manières d’accéder à l’information :
- (chrono)logique, comme lorsqu’on lit page après page, ligne après ligne, jusqu’à atteindre la fin de la publication,
- thématique, comme lorsqu’on va à la table des matières pour sauter directement à la partie qui nous intéresse, à condition que le contenu soit découpé en unités significatives,
- transversal, comme lorsqu’on suit une section « articles liés » fondée sur la similarité du contenu, définie manuellement avec des tags et mots-clés ou apprise par une analyse thématique par IA, ou encore des renvois explicites. Par exemple, la plupart des sites ont des archives listant toutes les pages portant un certain tag ou mot-clé, et les livres ont des glossaires.
- par indices, comme lorsqu’on présente une bibliographie de publications plus approfondies ou une section « pour en savoir plus » à la fin du contenu, ou lorsqu’on ouvre sur un contenu ultérieur,
- par les sources, en suivant les références, généralement notes de bas de page ou notes de marge, vers les publications d’où l’information est extraite, surtout à des fins de vérification,
- recherche d’information, autrement dit un moteur de recherche.
Il faut tous les prendre en charge à la fois, parce qu’ils sont complémentaires et que le meilleur mode d’accès dépend du contexte, des connaissances initiales et des besoins du lecteur. Aucun de ces modes n’est supérieur aux autres. Cela signifie qu’il faut glisser pas mal de mots-clés dans votre rédaction, afin que l’analyse de contenu fondée sur les mots-clés et la recherche d’information par mots-clés fonctionnent comme prévu.
Un manuel ou une documentation n’est pas un cours, mais s’en tenir à une liste sèche de fonctionnalités, de contrôles d’interface et de leurs définitions est… trop sec. Il faut créer des liens entre les contenus, et pas seulement des liens HTML. Dans Ansel, les flux de travail partent d’un objectif et déroulent les outils nécessaires pour l’atteindre. La documentation part des outils et présente comment et où les utiliser. Mais ce sont les deux extrémités du spectre, et la réalité se situe toujours un peu entre les deux.
De toute façon, la connaissance est un graphe de réseau . Il faut simplement veiller aux liens entre les nœuds. Ils sont au moins aussi importants que le contenu lui-même.
Mise en pratique dans Ansel
Ansel utilise Hugo comme CMS, à la fois pour la documentation et pour le reste du site web. La mise en œuvre pratique des principes énoncés ci-dessus doit donc composer avec les fonctionnalités de base de Hugo.
Accès (chrono)logique et thématique
Le contenu Hugo est organisé en sections , qui sont essentiellement des sous-dossiers du dossier principal /content. Ces sous-dossiers peuvent être imbriqués indéfiniment. Le thème du site affiche l’arborescence de toutes les sections dans la barre latérale gauche sur les écrans larges, typiquement sur ordinateur. Les niveaux supérieurs des sections et sous-sections peuvent être repliés ou dépliés à la demande de l’utilisateur. Cette arborescence fournit la table des matières de premier niveau, qui sert d’accès thématique.
Au sein des sections, l’ordre relatif des pages peut être défini manuellement à l’aide du paramètre weight dans l’en-tête Markdown, comme ceci :
Le paramètre weight est optionnel. S’il n’est pas utilisé, les listes de pages utilisent généralement la date pour ordonner le contenu, mais elles peuvent aussi employer un ordre alphabétique sur le titre de la page. Cet ordonnancement fournit l’accès (chrono)logique.
À l’intérieur des pages, s’il y a plus de deux sections dans le contenu, définies par des titres de second niveau, par exemple <h2> en HTML ou ## en Markdown, une table des matières interne sera automatiquement ajoutée par Hugo dans la barre latérale droite sur les écrans larges, c’est-à-dire sur ordinateur.
Accès transversal
Les tags peuvent être définis sur le site à l’aide du paramètre tags dans l’en-tête Markdown, comme ceci :
Les tags sont optionnels et sont affichés comme des liens cliquables à plusieurs endroits dans le thème du site. Cliquer sur un tag ouvre son archive, qui liste toutes les pages portant ce tag. Cela fournit un accès transversal.
Les rédacteurs sont aussi encouragés à ajouter des liens croisés dans leurs contenus, depuis des pages du site vers d’autres pages du site, afin de favoriser l’accès transversal. Les concepts qui possèdent une entrée sur le site devraient être transformés en liens vers la page qui décrit chaque concept.
Accès par indices
Les rédacteurs sont libres d’ajouter une section Bibliographie ou Pour en savoir plus à la fin de leurs pages, avec une liste de publications et de liens. Ces publications peuvent être internes ou externes au projet Ansel. Elles peuvent aussi être périphériques au sujet traité dans le contenu.
Il est aussi possible de terminer une page en ouvrant sur l’étape logique suivante, lorsque l’on écrit à propos de flux de travail ou de modules.
Accès par les sources
Hugo prend en charge le Markdown étendu, qui prend en charge les notes de bas de page . Celles-ci sont recommandées pour référencer les sources, comme ceci :
1L'observateur typique a un seuil de différence juste perceptible, Delta E, de 2,3[^1]
2
3[^1]: Un auteur, un éditeur, _Une étude à grande échelle, en conditions réelles, des paramètres de vision sur des étudiants blancs, riches et instruits du Rochester Institute of Technology_, (une certaine année). [URL](https://doi.org/xxxxx)À ce stade, Ansel n’a adopté aucun format académique particulier pour les citations de sources, même si le style de citation IEEE semble le plus adapté à l’approche par notes de bas de page avec index numérique.
Veillez à inclure le DOI de la publication, ou au moins une URL pérenne à partir de laquelle elle pourra être retrouvée aujourd’hui comme à l’avenir.
Recherche d’information
Pour l’instant, c’est Chantal qui gère cette partie. L’index du site est mis à jour manuellement et périodiquement.
Lignes directrices
L’écriture, même technique, est un art qu’il est difficile de réduire à un ensemble de règles fixes ou de bonnes pratiques, parce que cela varie selon le contexte. Il faut veiller à ne pas être plus royaliste que le roi. Une bonne règle empirique consiste à écrire pour résoudre des problèmes, ce qui signifie commencer par vous demander pourquoi et depuis où le lecteur a atterri sur la page que vous êtes en train d’écrire :
- quel type de connaissances le lecteur est-il censé déjà posséder ?
- idéalement, le lecteur devrait connaître ces prérequis, donc vous pouvez commencer par une liste de liens,
- tout ce qui n’est pas dans cette liste devrait être défini et expliqué sur votre page,
- quel type de tâche le lecteur essaie-t-il d’accomplir, ce qui l’a conduit jusqu’à cette page ?
- cherche-t-il un aide-mémoire rapide, un mode d’emploi détaillé, ou un arrière-plan théorique ? Vous devrez peut-être en choisir arbitrairement un.
- cela déterminera quels indices vous pouvez ajouter dans le texte pour améliorer le réseau de connaissances,
- cela devrait probablement influencer l’angle général de votre contenu ainsi que sa longueur et sa profondeur.
Une bonne manière d’évaluer la qualité de la documentation consiste à regarder les questions les plus fréquemment posées, ou les sujets les moins bien compris, sur les forums. Si le sujet est déjà couvert mais que les questions continuent d’affluer, cela peut signifier que la documentation n’est pas claire ou que les pages pertinentes sont enfouies dans le réseau et pas assez faciles à découvrir.
Translated from English by : Aurélien Pierre, ChatGPT. In case of conflict, inconsistency or error, the English version shall prevail.