Conseils pour une recherche optimale
Cette page a été traduite par PageTurner AI (bêta). Non approuvée officiellement par le projet. Vous avez trouvé une erreur ? Signaler un problème →
DocSearch fonctionne avec presque tous les sites web, mais nous avons constaté que certaines structures de site produisent des résultats plus pertinents ou un temps d'indexation plus rapide. Cette page présente des conseils pour tirer le meilleur parti de DocSearch.
Utiliser un sitemap.xml
Si vous fournissez un sitemap dans votre configuration, DocSearch l'utilisera pour accéder directement aux pages à indexer. Les pages sont toujours crawlées, ce qui signifie que nous extrayons tous les liens conformes.
Nous vous recommandons vivement d'ajouter un sitemap.xml à votre site si vous n'en avez pas déjà un. Cela accélérera l'indexation et vous donnera plus de contrôle sur les pages à inclure ou non dans l'index.
Les sitemaps sont également considérés comme une bonne pratique pour d'autres aspects, notamment le référencement (plus d'informations sur les sitemaps).
Structurer la hiérarchie de l'information
DocSearch fonctionne mieux avec une documentation structurée. La pertinence des résultats repose sur la hiérarchie structurelle du contenu. En termes simples, nous lisons les balises <h1> à <h6> de votre page pour déduire la hiérarchie de l'information. Cette hiérarchie apporte un contexte à vos enregistrements.
Une documentation commence par expliquer des concepts généraux avant d'aborder des spécificités. Cela se traduit dans votre balisage HTML par la hiérarchie des titres utilisés. Par exemple, les concepts sous un <h4> sont plus spécifiques que ceux sous un <h2> dans la même page. Plus une information apparaît tôt dans la page, plus son classement est élevé.
DocSearch utilise cette structure pour affiner la pertinence des résultats et permettre un éventuel filtrage. Les documentations suivant ce modèle obtiennent généralement de meilleurs résultats de recherche.
Déterminer la profondeur optimale de votre arborescence documentaire et segmenter votre contenu sont deux tâches complexes. Pour les grandes pages, nous recommandons 4 niveaux (de lvl0 à lvl3). Un minimum de trois niveaux distincts est conseillé.
Notez que vous pouvez utiliser des classes plutôt que des balises <hX> (ex. <span class="title-X"> ). Vous devrez alors mettre à jour la valeur selectors dans votre configuration.
Définir une classe unique pour le conteneur de contenu
DocSearch extrait le contenu basé sur la structure HTML. Nous recommandons d'ajouter une class personnalisée à l'élément HTML englobant tout votre contenu textuel. Cela aidera à cibler les sélecteurs sur le contenu pertinent.
Cet identifiant unique rendra votre configuration plus robuste en garantissant que le contenu indexé est pertinent. C'est la méthode la plus fiable pour exclure les éléments non pertinents des en-têtes, barres latérales et pieds de page.
Ajouter des ancres aux titres
Lorsque vous utilisez des titres (comme mentionné ci-dessus), ajoutez une ancre personnalisée à chacun d'eux. Les ancres sont définies par des attributs HTML (name ou id) sur les en-têtes, permettant aux navigateurs de défiler directement à la position correspondante. Elles sont accessibles via un lien contenant # suivi de l'ancre.
DocSearch respectera ces ancres et amènera automatiquement vos utilisateurs à l'ancre la plus proche du résultat sélectionné.
Marquer la page active dans la navigation
Si votre navigation comporte plusieurs niveaux, nous recommandons de marquer chaque niveau actif avec une classe CSS personnalisée. Cela aidera DocSearch à déterminer où la page actuelle se situe dans la hiérarchie du site.
Par exemple, si votre page troubleshooting.html se trouve dans le menu "Installation" de votre barre latérale, ajoutez une classe CSS personnalisée aux liens "Installation" et "Troubleshooting".
Le nom de la classe CSS importe peu, tant qu'il peut être utilisé dans un sélecteur CSS.
Cohérence de votre contenu
La cohérence est un pilier d'une documentation significative. Elle accroît l'intelligibilité d'un document et réduit le temps nécessaire pour trouver l'information recherchée. Le sujet du document doit être identifiable et son plan clairement délimité.
La hiérarchie doit toujours avoir la même structure. Essayez d'éviter les enregistrements orphelins comme les introductions/conclusions ou les apartés. Les sélecteurs doivent être efficaces pour chaque document et mettre en lumière la hiérarchie appropriée. Ils doivent cibler précisément les éléments selon leur niveau. Veillez à éviter l'effet de bord en captant des éléments superflus inattendus.
Les sélecteurs doivent extraire l'information des pages web de documentation réelles et rester inefficaces sur les autres (page d'accueil, table des matières, etc.). Nous recommandons aux mainteneurs de définir une classe dédiée pour le conteneur DOM principal incluant le contenu documentaire, comme .DocSearch-content.
Une documentation étant par essence interactive, il est crucial de verbaliser les concepts avec un vocabulaire standardisé. Cette redondance, renforcée par l'expérience de recherche (menu déroulant), permet même une expérience d'apprentissage au fil de la saisie. La façon de présenter l'information joue un rôle clé pour guider l'utilisateur vers la connaissance retrouvée. Vous pouvez aussi utiliser la fonctionnalité de synonymes.
Évitez les doublons en privilégiant l'unicité
Plus la lecture d'une documentation est chronophage, plus son utilisation devient pénible et suscite de réticence. Évitez les points obscurs ou les documents fourre-tout. En plus d'être inutile, un document trop général peut s'avérer confus et contre-productif.
Les doublons introduisent du bruit et induisent les utilisateurs en erreur. C'est pourquoi vous devez vous concentrer sur le contenu pertinent et éviter de dupliquer l'information (pages d'accueil reprenant tout le contenu, résumés redondants, etc.). Si des doublons sont inévitables car relevant de jeux de données distincts (ex: versions différentes), utilisez les facettes.
Concision
Ce qui est clairement conçu s'exprime clairement et avec concision.
Nous vous recommandons vivement la lecture de cet article de blog : Comment créer une recherche utile pour la documentation technique.