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 Benutzer*innen ein Tool auswählen, um nur die für dieses Tool relevanten Inhalte anzuzeigen, da Tools möglicherweise unterschiedliche konzeptionelle oder verfahrensorientierte Informationen enthalten.
Benutzer*innen können den Toolumschalter beim Lesen der Dokumentation auf zwei Arten verwenden.
-
Erkunden – Bei Aufgaben, die mit verschiedenen Tools durchgeführt werden können, weist der Toolumschalter darauf hin, dass es mehrere Möglichkeiten zur Ausführung einer Aufgabe gibt. Verwende beispielsweise die GitHub CLI oder den GitHub Desktop anstelle der GitHub-Benutzeroberfläche.
-
Zielgerichtetes Vorgehen – Wenn Personen 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 Personen genau das finden können, was sie benötigen.
Verwenden von Tooltags
Sie können einem Artikel Toolumschalter hinzufügen, indem Sie Tooltags im Markdown verwenden. Tooltags sind Liquid-Tags, die Inhalte umschließen, die auf einer bestimmten Toolumschalter-Registerkarte angezeigt werden sollen.
Der folgende Codeblock z. B. zeigt Inhalte für drei verschiedene Tools an.
{% vscode %}
This content is specific to Visual Studio Code.
{% endvscode %}
{% visualstudio %}
This content is specific to Visual Studio.
{% endvisualstudio %}
{% jetbrains %}
This content is specific to JetBrains IDEs.
{% endjetbrains %}
Standardmäßig wird das erste im Markdown verwendete 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.
Wann Tooltags verwendet werden sollten
Tooltags sollten nur dann verwendet werden, wenn ein Artikel toolspezifische Informationen benötigt, um Benutzer*innen beim Ausführen ihrer Aufgaben zu unterstützen.
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.
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. 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. Beispiel: vscode: 'Visual Studio Code'.
Füge neue Tools in alphabetischer Reihenfolge hinzu.