Rechercher dans le blog

La doc du SDK JavaScript d'ArcGIS est disponible au format Markdown

Le site de documentation public de l’ArcGIS Maps SDK for JavaScript a été mis à jour afin d’intégrer une versions Markdown pour de nombreuses pages. Cette évolution permet aux machines et aux agents IA de traiter plus facilement et plus efficacement le contenu de la documentation. 
 
En plus de l’ajout de l’infrastructure nécessaire à la conversion des pages MDX et HTML en Markdown, les pages disposant d’une version Markdown proposent désormais un bouton Copy as Markdown en haut à droite, au-dessus de la table des matières. Pour les pages contenant des exemples de code, ce bouton se trouve dans la barre d’outils supérieure, à gauche.
 
La documentation mise à jour est accessible à l’adresse suivante : https://developers.arcgis.com/javascript/latest. Dans cet article, nous allons discuter des évolutions qui ont motivé ces évolutions, et nous verrons  quelques exemples de ces ajouts au format Markdown. 

Pourquoi proposer la documentation au format Markdown ?

L’ajout de versions Markdown des pages est une pratique de plus en plus répandue sur les sites web, car ce format permet aux machines et aux agents de traiter plus facilement le contenu des sites. Cela présente plusieurs avantages : réduire la quantité de balisage lié à la présentation qu’un agent doit analyser et recentrer le contexte sur le contenu même de la documentation. 

Pourquoi le Markdown est-il plus facile à lire pour les machines et les agents ?

Le Markdown permet de supprimer les éléments liés à la présentation et à l’interface utilisateur, tels que les boutons, les menus de navigation, les aperçus interactifs ou encore les styles, tout en conservant les informations utiles aux lecteurs et aux agents. Une bonne documentation Markdown préserve l’information, et non sa mise en forme, ce qui rend sa lecture plus économe en tokens et les informations plus facilement exploitables par les machines.
La page de documentation "Location Style"...

... et son équivalent au format Markdown, qui garde le contenu pertinent et supprime les éléments de présentation et l'interface utilisateur
Quelles pages du SDK JavaScript sont disponibles au format Markdown ?

Le format Markdown est actuellement disponible pour les principales catégories de pages de la documentation :
Par exemple, la page /get-started/ possède son équivalent au format Markdown /get-started.md, tout comme la page /tutorials/display-a-map/, disponible également sous la forme /tutorials/display-a-map.md.
Les instructions pertinents, les liens, et les exemples de code restent disponibles

Comment accéder à la documentation Markdown du SDK JavaScript ?

Pour les développeurs : vous pouvez facilement accéder à la version Markdown d’une page en ajoutant .md à la fin de son URL. Le moyen le plus simple d’accéder à cette version pour une page donnée consiste à cliquer sur la flèche située à côté du bouton "Copy as Markdown", au-dessus de la table des matières, puis à sélectionner "View Markdown".vSi vous souhaitez simplement copier le contenu Markdown sans accéder à la page correspondante, cliquez directement sur le bouton "Copy as Markdown". Le contenu de la page sera alors copié dans le presse-papiers.
Pour les agents et GitHub Copilot : copiez la version Markdown d’une page dans un assistant IA lorsque vous souhaitez lui fournir un contexte documentaire ciblé, sans les éléments d’interface du site qui l’entourent. Par exemple, pour des tâches de développement, le contenu Markdown permet de fournir à GitHub Copilot la documentation, les liens vers les API, les instructions et les exemples de code pertinents, sans les éléments d’interface du site qui pourraient détourner son attention.

Donner son avis

Esri invite les utilisateurs à lui faire part de leurs retours concrets lorsqu’ils constatent des problèmes d’affichage ou de fonctionnement liés aux fonctionnalités Markdown.

Voici quelques exemples de problèmes pouvant être signalés : 
  • Contenu manquant
  • Mise en forme peu claire 
  • Contexte de code incorrect ou incomplet 
  • Liens qui ne fonctionnent pas correctement
  • Contenu qui s'affiche correctement dans l'interface du site, mais pas dans la version Markdown
Pour signaler un problème concernant la version Markdown d’une page, sélectionnez « No » sous la question « Was this page helpful? », en bas de la page, puis décrivez le problème rencontré.

Remarque : si vous avez besoin d’un rappel sur la procédure à suivre pour transmettre vos retours, survolez l’icône d’information associée à l’intitulé "Have feedback?", sous le bouton Copy as Markdown. Une infobulle affichera les instructions à suivre.

Aucun commentaire:

Enregistrer un commentaire