Liens vers les Termes du Glossaire et Infobulles : Règles de Rédaction

Un lien vers un terme du glossaire relie un terme à sa première mention significative vers l’unique page qui possède sa définition complète. Le lien aide le lecteur à comprendre un vocabulaire inconnu sans interrompre l’article, et offre aux robots d’exploration une relation cohérente entre le terme et sa page d’entité canonique.

Une URL canonique est la version préférée d’une page lorsque plusieurs URL contiennent un contenu identique ou sensiblement similaire.

Cette phrase est l’élément concret. L’ancre est le terme exact, la destination est son entrée de glossaire canonique, et la phrase environnante reste compréhensible sans ouvrir le lien. Sur les systèmes qui le supportent, le même lien peut exposer une courte infobulle de définition au survol ou au focus clavier. La page liée — et non l’infobulle — reste la source de vérité.

Pourquoi cet élément est important

Les lecteurs n’arrivent pas tous avec le même vocabulaire. Un spécialiste peut reconnaître « URL canonique » immédiatement, tandis qu’un acheteur ou un nouveau membre de l’équipe peut avoir besoin d’une définition. Expliquer chaque terme entre parenthèses ralentit le texte destiné aux experts ; n’en expliquer aucun exclut les novices. Un lien vers un terme du glossaire crée une échappatoire discrète : continuez si le terme vous est familier, ou ouvrez sa définition s’il ne l’est pas.

La règle de la première mention est importante car l’incertitude s’accumule. Si un lecteur comprend mal un terme au deuxième paragraphe, chaque affirmation ultérieure reposant sur ce terme devient plus difficile à évaluer. Lier la première occurrence significative dissipe l’incertitude avant qu’elle ne se propage. Cette règle ne signifie pas « liez la première chaîne de caractères correspondante ». Un terme dans un titre, une étiquette de navigation, un exemple de code ou un accroche peut ne pas encore porter le sens utilisé dans l’explication.

L’extractabilité par les machines est la capacité d’un logiciel à préserver une relation une fois la présentation supprimée. Une ancre descriptive et une destination stable créent une arête explicite : cette page utilise le concept, et cette page de glossaire le définit. Des arêtes cohérentes renforcent quelle URL possède la définition. Elles ne créent pas un graphe de connaissances formel ni ne garantissent la visibilité, mais elles réduisent l’ambiguïté qu’un robot d’exploration résoudrait autrement par la seule proximité.

L’excès de liens annule ces avantages. Lorsque chaque terme répété est lié, la page cesse de signaler les priorités. Les lecteurs font face à un champ de sorties concurrentes, les utilisateurs de technologies d’assistance entendent la même destination à plusieurs reprises, et les machines reçoivent de nombreuses arêtes redondantes plutôt qu’un petit ensemble de relations délibérées. Un seul lien canonique à la première mention significative est donc la règle par défaut, et non un minimum à répéter dans chaque section.

Quand l’utiliser

Utilisez l’élément lorsque les trois conditions sont réunies :

1. Le terme a une page de glossaire canonique, plutôt que plusieurs définitions quasi identiques.
2. La compréhension du terme aide matériellement le lecteur à comprendre la page actuelle.
3. La première utilisation significative peut porter une ancre descriptive sans déformer la phrase.

Les bons candidats incluent la terminologie spécialisée, les acronymes lors de leur première utilisation développée, les normes nommées, les indicateurs et les mots dont le sens dans le domaine diffère de l’usage courant. Une infobulle peut prévisualiser une courte définition ; la page de glossaire complète traite des limites, des exemples, des sources et des termes connexes.

Les cas limites sont ceux où l’élément est le plus souvent mal utilisé :

• Vocabulaire courant : ne liez pas un mot familier simplement parce qu’une entrée de glossaire existe.
• Mentions incidentes : si l’article nomme un concept mais ne s’y appuie pas, un lien crée une sortie inutile.
• Mentions répétées : après la première utilisation liée, laissez le terme en texte nu, sauf si une page longue et multi-parties crée un contexte de lecture véritablement indépendant.
• Texte d’ancre ambigu : « cette approche », « en savoir plus » et « l’indicateur » n’identifient pas l’entité du glossaire. Liez le terme lui-même.
• Aucune destination canonique : ne remplacez pas par un résultat de recherche, une archive d’étiquettes ou un article vaguement lié. Utilisez un texte simple jusqu’à ce que la définition canonique existe.
• Définition déjà fournie intégralement : si le glossaire n’ajoute aucune profondeur utile, un deuxième détour définitionnel peut être inutile.
• Détournement commercial : un lien de glossaire n’est pas un appel à l’action déguisé pour un produit. Les pages produit, les formulaires d’inscription et les pages de tarification répondent à des intentions de lecture différentes.

Appliquez les règles de rédaction d’éléments communes avant d’improviser. Leur règle de priorité impose aux auteurs de sélectionner un élément selon son objectif. Si l’objectif est de relier un terme nommé à sa définition canonique, utilisez cette relation typée plutôt qu’un lien en ligne générique stylisé pour ressembler à l’élément.

Où le placer

Placez le lien sur la première mention significative dans le texte : la première phrase utilisant le concept dans le sens de la destination. Si le terme apparaît d’abord dans le titre ou un H2, liez sa première utilisation dans le paragraphe suivant. Les titres doivent rester des étiquettes de section stables plutôt que de grandes cibles de navigation.

Pour un acronyme, écrivez le terme complet suivi de l’abréviation et liez le terme complet : retrieval-augmented generation (RAG). Les occurrences ultérieures peuvent utiliser RAG sans lien.

Ne placez pas un lien de terme du glossaire :

• à l’intérieur d’un autre lien, bouton ou carte cliquable ;
• à côté d’un second lien sur le même texte d’ancre ;
• dans du code, une URL, une adresse e-mail ou un texte littéral saisi par l’utilisateur ;
• dans un titre uniquement pour satisfaire la règle de la première mention ;
• dans chaque ligne d’un tableau alors qu’une définition liée dans l’introduction peut établir le terme ;
• immédiatement à côté d’un marqueur de citation si les deux cibles deviennent visuellement ou opérationnellement indistinctes ;
• à l’intérieur d’un déclencheur d’infobulle distinct du lien lui-même.

Si une phrase contient plusieurs termes inconnus, liez uniquement les termes nécessaires à la compréhension de cette phrase. Trois liens de glossaire ou plus dans une même phrase sont un signe que le texte présuppose trop de vocabulaire. Reformulez la phrase, définissez un concept sur place ou divisez l’explication avant d’ajouter d’autres sorties.

Anatomie

Le spécimen annoté comporte six zones :

1. Ancre du terme : le terme visible ou le nom complet développé, sans « en savoir plus ».
2. Destination canonique : une URL de glossaire stable qui possède la définition.
3. Phrase de contexte : suffisamment de texte pour comprendre pourquoi le terme apparaît, même si le lien n’est pas ouvert.
4. Style du lien : le traitement standard des liens en ligne du site ; la couleur n’est pas le seul indicateur.
5. Indicateur de focus : un état clavier visible qui n’est pas coupé par le paragraphe ou l’infobulle.
6. Infobulle facultative : un aperçu bref lié au lien lui-même, jamais un contrôle séparé uniquement iconique.

La présentation peut changer sans modifier l’ancre, la destination ou le comportement de première mention.

Exemples de design

Chaque variante préserve le même lien sémantique.

Lien en ligne par défaut : la référence de base. Il fonctionne avec JavaScript désactivé, en mode lecture, dans les annotations d’impression et sur les appareils sans survol.

Infobulle de définition au focus ou au survol : une amélioration pour le contenu éducatif dense. L’aperçu fait une ou deux phrases et ne contient jamais de liens, boutons, citations ou contrôles de formatage.

Mobile et tactile : le premier appui suit le lien, sauf si le produit propose un modèle de divulgation établi et accessible. N’obligez pas les utilisateurs à découvrir qu’un appui ouvre un aperçu et qu’un second appui navigue, à moins que cette interaction soit cohérente sur l’ensemble du site et clairement communiquée.

Fond sombre : le lien, l’anneau de focus, le texte de l’infobulle et la bordure de l’infobulle conservent un contraste clair. Ne supprimez pas le soulignement simplement parce que la couleur d’accent est vive.

Paramètres

L’URL canonique et l’ancre visible sont des décisions de contenu. Le comportement de l’infobulle appartient au moteur de rendu. Séparer ces sources empêche une fonctionnalité d’interface facultative de modifier le sens du lien.

Ne déduisez jamais href de term : les homonymes peuvent partager une orthographe tout en nécessitant des destinations différentes. Extrayez une infobulle de l’enregistrement du glossaire uniquement lorsque sa définition courte est révisée pour être utilisée en dehors de la page.

Syntaxe et exemples de code

Les trois formats préservent un lien normal comme cœur. Les champs nommés constituent un contrat portable ; une plateforme peut les restituer avec un bloc natif, un plugin ou une étape de prétraitement.

Directive Markdown portable

The :::glossary-link{href="/glossary/canonical-url/" definition="A canonical URL is the preferred version of a page when duplicate or similar URLs exist." tooltip="true"}canonical URL::: consolidates signals on the preferred page.

Si le pipeline de publication ne supporte pas les directives en ligne, utilisez le Markdown ordinaire et omettez l’infobulle :

The [canonical URL](/glossary/canonical-url/) consolidates signals on the preferred page.

Shortcode Hugo

The {{< glossary-term-link href="/glossary/canonical-url/" definition="A canonical URL is the preferred version of a page when duplicate or similar URLs exist." tooltip="true" >}}canonical URL{{< /glossary-term-link >}} consolidates signals on the preferred page.

Cette notation spécifie le mappage requis ; elle n’oblige pas les auteurs à introduire un nouveau shortcode dans un projet qui gère déjà les liens de glossaire via le rendu Markdown ou le prétraitement du contenu. La solution de repli rendue doit toujours être un élément <a href> ordinaire.

WordPress

<!-- wp:amicited/glossary-link {"href":"/glossary/canonical-url/","definition":"A canonical URL is the preferred version of a page when duplicate or similar URLs exist.","tooltip":true} -->
<a href="/glossary/canonical-url/">canonical URL</a>
<!-- /wp:amicited/glossary-link -->

Le contenu exporté doit conserver l’ancre et le href même lorsque les métadonnées d’infobulle ne sont pas disponibles.

Exemples

Bon

Sélectionnez une URL canonique pour les pages sensiblement similaires afin que les signaux d’indexation pointent vers la version préférée.

Dans l’article rendu, « URL canonique » renvoie vers /glossary/canonical-url/ à cette première utilisation significative. L’ancre nomme l’entité exactement, la phrase fournit suffisamment de contexte local pour continuer la lecture, et les occurrences ultérieures restent en texte brut. Le lecteur peut choisir si la définition complète est nécessaire.

Mauvais

Sélectionnez une page préférée pour les pages similaires. Votre URL canonique doit ensuite référencer l’URL canonique dans chaque section.

Cet exemple échoue deux fois. « Page préférée » est un terme apparenté mais pas le terme exact que la destination définit, donc la relation est moins explicite. Répéter le lien d’URL canonique dans chaque section ajoute des sorties sans ajouter de sens. La correction appropriée est de lier « URL canonique » une fois à sa première utilisation significative et de laisser les utilisations ultérieures sans lien.

Un autre mauvais motif est une icône d’information après un terme non lié. L’icône cache la destination aux lecteurs qui parcourent le texte du lien, crée une petite cible tactile et peut séparer l’infobulle de la relation de glossaire navigable.

Balisage Schema et accessibilité

Un lien de terme du glossaire n’a pas besoin de type Schema.org autonome. Il reste un lien à l’intérieur de l’Article, TechArticle ou WebPage englobant. Ne fabriquez pas de balisage DefinedTerm, mentions ou about pour chaque lien en ligne ; n’ajoutez de telles relations que via un modèle de données cohérent au niveau de la page, justifié par le contenu visible.

L’accessibilité commence par une ancre réelle. Elle doit être compréhensible dans son contexte, distinguable sans la seule couleur, accessible au clavier et visiblement ciblée. Les informations essentielles ne peuvent pas exister uniquement dans l’infobulle.

Si une infobulle est implémentée, associez-la à l’ancre à l’aide d’aria-describedby lorsqu’elle est visible. Ouvrez-la au focus clavier ainsi qu’au survol du pointeur, maintenez-la ouverte pendant que le pointeur se déplace sur l’infobulle et permettez à Échap de la fermer sans déplacer le focus. Ne placez pas de contrôles focalisables à l’intérieur d’une infobulle. Ne dépendez pas de l’attribut HTML title comme interface de définition : son minutage, sa présentation, son support tactile et son exposition aux technologies d’assistance sont incohérents. Un attribut title peut être supplémentaire, mais ce n’est ni le nom accessible, la description, ni la définition canonique.

Le lien doit naviguer lorsque les scripts échouent. Sur les appareils tactiles, privilégiez la navigation directe plutôt que l’imitation du survol. Si l’amélioration ne peut pas répondre à ces exigences, livrez le lien simple.

Règles de rédaction

Liez le terme exact ou sa forme complète non ambiguë. Limitez les ancres à un à huit mots et à moins de 80 caractères. N’incluez les articles tels que « un », « une » ou « le » que lorsqu’ils font partie d’un nom propre. Ne mettez pas en gras chaque ancre de glossaire ; le style de lien standard communique déjà l’interactivité, et l’accumulation d’emphase rend le texte technique bruyant.

Utilisez un lien de glossaire par terme par page par défaut. Un second lien n’est acceptable que lorsque du contenu consommé indépendamment — comme une longue annexe, une réponse FAQ autonome ou un module intégré — perdrait autrement la relation. Ne fixez pas de nombre minimum de liens de glossaire. Une page claire avec deux termes nécessaires est meilleure qu’une page avec dix sorties décoratives.

Les définitions des infobulles doivent faire 40 à 180 caractères et pas plus de deux phrases. Indiquez ce qu’est le terme, pas pourquoi le lecteur devrait cliquer. Utilisez un langage neutre et déclaratif. L’aperçu doit correspondre à la définition actuelle de la destination et devrait, si possible, provenir de l’enregistrement du glossaire afin que les mises à jour ne divergent pas.

Ne mettez jamais ce qui suit à l’intérieur du lien ou de l’infobulle :

• un autre lien, bouton, contrôle de formulaire ou icône interactive ;
• une allégation commerciale ou un appel à l’action ;
• une liste de citations ou une note de source ;
• une image, une vidéo, un tableau, un bloc de code ou une procédure en plusieurs étapes ;
• une définition qui entre en conflit avec la page canonique ou qui s’étend au-delà ;
• des instructions essentielles à la réalisation de la tâche du lecteur.

Vérifiez les homonymes manuellement. « Java », « conversion » ou « agent » peuvent désigner différentes entités. La phrase et la destination doivent résoudre la même signification. Ne changez jamais les destinations pour la distribution de liens ; la canonicalité est l’objectif.

Types d’articles qui l’utilisent

Le frontmatter postTypes[] identifie les formats pour lesquels cet élément fait partie documentée du système de contenu. Le tableau indique comment chaque format applique le même contrat de première mention.

Liste de vérification QA

• Destination canonique : le chemin est l’unique page de glossaire qui possède la définition ; ce n’est pas une URL de recherche, d’étiquette, de produit ou d’article connexe.
• La destination existe : le fichier de contenu existe maintenant ou le chemin apparaît dans le registre canonique approuvé pour la même version.
• La signification correspond : l’ancre et la destination se réfèrent au même sens du terme, y compris pour les acronymes ambigus et les homonymes.
• Première mention significative : le lien apparaît dans le texte avant les utilisations ultérieures, pas dans un titre ou un exemple de code simplement parce que cette occurrence est apparue en premier dans l’ordre source.
• Ancre exacte : les mots liés nomment le terme ou sa forme complète non ambiguë ; il n’y a pas de « cliquez ici » ou de substitut vague.
• La phrase locale fonctionne : un lecteur peut comprendre la phrase sans ouvrir la destination ni déclencher l’infobulle.
• Un-par-terme par défaut : les occurrences répétées restent sans lien, sauf si un contexte de lecture indépendant documenté justifie un autre lien.
• Pas d’amas de liens : la phrase et le paragraphe restent lisibles ; les termes inconnus excessifs sont réécrits plutôt que couverts de liens.
• Parité de l’infobulle : tout aperçu correspond à la définition canonique et reste entre 40 et 180 caractères.
• Amélioration progressive : l’ancre fonctionne toujours lorsque les scripts, le survol ou le style de l’infobulle sont indisponibles.
• Comportement clavier : le focus est visible ; l’infobulle apparaît au focus, peut être fermée avec Échap et ne contient pas de contrôles focalisables.
• Comportement tactile : le lien a une taille de cible normale et ne nécessite pas de survol ni une interaction à deux appuis inexpliquée.
• Retenue des données structurées : aucune relation schema non supportée ou type d’élément inventé n’est émis.
• Sortie portable : Markdown, Hugo et WordPress préservent le même terme et le même href canonique même si les métadonnées d’infobulle sont supprimées.
• Statut des captures d’écran : les commentaires de capture restent des instructions non rendues jusqu’à ce que les actifs nommés existent ; aucune image inexistante n’est référencée.

FAQ

Le modèle academy restitue les questions du frontmatter révisées couvrant l’éligibilité, la première mention, le périmètre de l’infobulle, la cohérence canonique et les limites de liens.