À propos des sélecteurs d’outils
Dans certains articles, nous écrivons du contenu adapté aux différents outils (l’IU GitHub, GitHub CLI, GitHub Desktop, cURL, Codespaces, VS Code, l’API GraphQL, etc.) Le sélecteur d’outils permet aux utilisateurs de sélectionner un outil afin de voir uniquement le contenu pertinent pour cet outil, car les outils peuvent comporter des informations conceptuelles ou procédurales distinctes. Les utilisateurs peuvent utiliser le sélecteur d’outils de deux façons pour lire la documentation.
Exploration Pour les tâches qui peuvent être effectuées avec différents outils, le sélecteur d’outils signale aux utilisateurs qu’il existe plusieurs façons d’effectuer une tâche. Par exemple, en utilisant GitHub CLI ou GitHub Desktop, à la place de l’IU GitHub.
Droit au but Quand une personne sait comment elle souhaite effectuer une tâche et qu’elle n’a pas besoin de voir d’options supplémentaires, le sélecteur d’outils supprime le contenu moins pertinent pour qu’elle puisse trouver exactement ce dont elle a besoin.
Utilisation des étiquettes d’outils
Nous utilisons des étiquettes d’outils pour diviser les informations relatives à chaque outil. En de rares occasions, nous ajoutons de nouveaux outils.
Les étiquettes d’outils représentent une paire clé-valeur. La clé est l’étiquette que vous utilisez pour faire référence à l’outil dans l’article, et la valeur correspond à la façon dont l’outil est identifié dans le sélecteur d’outils en haut de l’article. Les outils existants se trouvent dans lib/all-tools.js au sein du dépôt GitHub Docs.
Quand utiliser les étiquettes d’outils
Nous utilisons les étiquettes d’outils uniquement si un article doit contenir des informations spécifiques à un outil pour aider les personnes à accomplir leurs tâches. Si les informations conceptuelles ou les étapes procédurales d’une tâche diffèrent considérablement selon l’outil utilisé, et si nous souhaitons que les utilisateurs puissent accomplir la tâche avec différents outils, nous utilisons des étiquettes d’outils pour présenter les informations appropriées dans un article.
N’utilisez pas le sélecteur d’outils uniquement pour afficher des exemples dans différentes langues. Utilisez le sélecteur d’outils uniquement si les tâches ou les concepts décrits dans un article changent en fonction de l’outil utilisé.
Comment utiliser les étiquettes d’outils
Les étiquettes d’outils sont des étiquettes Liquid qui wrappent du contenu spécifique à un outil.
Placez les outils par ordre alphabétique. Par défaut, la première étiquette d’outil est sélectionnée pour un article. Vous pouvez définir un autre outil par défaut pour un article en spécifiant une propriété defaultTool: dans les informations préliminaires de l’article. Pour plus d’informations, consultez le README relatif au contenu.
Vous pouvez également lier un article à un outil spécifique sélectionné en ajoutant ?tool=TOOLNAME à la fin du lien. Pour plus d’informations, consultez « Guide de style ».
Incluez uniquement huit outils différents au maximum dans un article. Si vous incluez des outils supplémentaires, les onglets du sélecteur d’outils débordent sur la table des matières d’un article, ce qui empêche les utilisateurs d’utiliser le sélecteur d’outils ou la table des matières. Il est peu probable que vous ayez besoin d’inclure huit outils distincts dans un article. En règle générale, prévoyez d’utiliser le moins d’outils distincts possible dans un article.
Ajout de nouveaux outils
GitHub Docs documente et gère les balises d’outils pour les produits GitHub, les outils développés GitHub, puis sélectionnez les extensions tierces développées en collaboration avec GitHub.
Les nouveaux outils ne sont ajoutés que lorsqu’ils sont le seul moyen de documenter avec précision quelque chose pour un utilisateur spécifique. Si un rédacteur détermine que l’ajout d’un nouvel outil est le seul moyen de documenter avec précision quelque chose, il doit proposer le nouvel outil dans un plan de contenu. La personne qui passe en revue le plan de contenu doit se demander s’il existe d’autres moyens de répondre aux besoins de documentation sans ajouter de nouvel outil. Si un nouvel outil est le seul moyen de créer une documentation précise, il doit être ajouté. S’il existe une autre solution de contenu qui n’ajoute pas de nouvel outil, vous devez utiliser cette option.
Pour ajouter un nouvel outil, ajoutez une entrée à l’objet allTools dans le fichier lib/all-tools.js en tant que paire clé-valeur. Ajoutez les nouveaux outils par ordre alphabétique.