Informationen zu Toolumschaltern
Manche Artikel sind auf bestimmte Tools zugeschnitten (die GitHub-Benutzeroberfläche, die GitHub CLI, der GitHub Desktop, das cURL-Tool, Codespaces, VS Code, die GraphQL-API usw.). Mit dem Toolumschalter können Benutzerinnen ein Tool auswählen, um nur die für dieses Tool relevanten Inhalte anzuzeigen, da Tools möglicherweise unterschiedliche konzeptionelle oder verfahrensorientierte Informationen enthalten. Benutzerinnen können den Toolumschalter beim Lesen der Dokumentation auf zwei Arten verwenden.
Erkunden: Bei Aufgaben, die mit verschiedenen Tools abgeschlossen werden können, weist der Toolumschalter Benutzer*innen darauf hin, dass es mehrere Möglichkeiten gibt, eine Aufgabe ausführen. Verwende beispielsweise die GitHub CLI oder den GitHub Desktop anstelle der GitHub-Benutzeroberfläche.
Zielgerichtetes Vorgehen: Wenn Benutzerinnen wissen, wie sie eine Aufgabe ausführen möchten und keine zusätzlichen Optionen anzeigen möchten, entfernt der Toolumschalter weniger relevante Inhalte, damit die Benutzerinnen genau das finden können, was sie benötigen.
Verwenden von Tooltags
Mit Tooltags können Informationen für jedes Tool separat angezeigt werden. In seltenen Fällen werden neue Tools hinzufügt.
Tooltags sind Schlüssel-Wert-Paare. Der Schlüssel entspricht dem Tag, den du zum Verweisen auf das Tool im Artikel verwendest, und der Wert gibt an, wie das Tool in der Toolauswahl oben im Artikel erkannt wird. Die vorhandenen Tools befinden sich in der lib/all-tools.js-Datei im GitHub Docs-Repository.
Wann Tooltags verwendet werden sollten
Tooltags sollten nur dann verwendet werden, wenn ein Artikel toolspezifische Informationen benötigt, um Benutzerinnen beim Ausführen ihrer Aufgaben zu unterstützen. Wenn sich die konzeptionellen Informationen oder verfahrensorientierten Schritte für eine Aufgabe in Abhängigkeit zum verwendeten Tool erheblich unterscheiden, und wenn es Benutzerinnen ermöglicht werden soll, eine Aufgabe mit verschiedenen Tools auszuführen, können Tooltags verwendet werden, um relevante Informationen in einem Artikel anzuzeigen.
Verwende den Toolumschalter nicht, um lediglich Beispiele in verschiedenen Sprachen anzuzeigen. Verwende den Toolumschalter nur, wenn sich die in einem Artikel beschriebenen Aufgaben oder Konzepte in Abhängigkeit des verwendeten Tools ändern.
Verwenden von Tooltags
Tooltags sind Liquid-Tags, die toolspezifische Inhalte umschließen.
Bringe Tools in eine alphabetische Reihenfolge. Standardmäßig wird der erste Tooltag für einen Artikel ausgewählt. Du kannst ein anderes Standardtool für einen Artikel festlegen, indem du eine defaultTool:-Eigenschaft in der Frontmatter des Artikels angibst. Weitere Informationen findest du in der Infodatei zu Inhalten.
Du kannst auch zu einem Artikel verlinken, bei dem ein bestimmtes Tool ausgewählt ist, indem du ?tool=TOOLNAME am Ende des Links hinzufügst. Weitere Informationen findest du unter Styleguide.
Behandle höchstens acht verschiedene Tools in einem Artikel. Mehr als acht Tools in einem Artikel führen dazu, dass die Tabs des Toolumschalters mit dem Inhaltsverzeichnis eines Artikels überlaufen, wodurch Benutzer*innen weder den Toolumschalter, noch das Inhaltsverzeichnis verwenden können. Es ist unwahrscheinlich, dass du jemals acht verschiedene Tools in einem Artikel behandeln musst. Im Allgemeinen solltest du so wenige verschiedene Tools wie möglich in einem Artikel behandeln.
Hinzufügen von neuen Tools
GitHub Docs dokumentiert und pflegt Tool-Tags für GitHub-Produkte, GitHub-entwickelte Tools und ausgewählte Erweiterungen von Drittanbietern, entwickelt in Zusammenarbeit mit GitHub.
Neue Tools werden nur dann hinzugefügt, wenn sie die einzige Möglichkeit sind, etwas für einen bestimmten Benutzerbedarf genau zu dokumentieren. Wenn Autor*innen feststellen, dass das Hinzufügen eines neuen Tools die einzige Möglichkeit ist, etwas genau zu dokumentieren, müssen sie das neue Tool in einem Plan zur Gestaltung der Inhalte vorschlagen. Wer auch immer den Plan für die Gestaltung der Inhalte überprüft, sollte alle alternativen Möglichkeiten in Betracht ziehen, um den Dokumentationsbedarf zu decken, ohne ein neues Tool hinzuzufügen. Wenn ein neues Tool die einzige Möglichkeit ist, eine genaue Dokumentation zu erstellen, sollte das neue Tool hinzugefügt werden. Wenn es eine alternative Inhaltslösung gibt, die kein neues Tool einschließt, sollte diese Lösung verwendet werden.
Um ein neues Tool hinzuzufügen, füge dem allTools-Objekt in der lib/all-tools.js-Datei einen Eintrag als Schlüssel-Wert-Paar hinzu. Füge neue Tools in alphabetischer Reihenfolge hinzu.