Inhalt eines GitHub-Docs-Artikels

Jeder Artikel enthält einige Standardelemente und kann konditionale oder optionale Elemente enthalten. Wir verwenden auch eine Standardreihenfolge für Inhalte innerhalb eines Artikels.

In diesem Artikel

Informationen zur Struktur eines Artikels

Innerhalb eines Artikels gibt es eine Standardreihenfolge der Inhaltsabschnitte. Jeder Artikel enthält erforderliche Elemente. Artikel enthalten auch konditionale und optionale Elemente, die beim Entwurf oder bei der Erstellung von Inhalten beschrieben werden. Die folgenden Richtlinien bieten weitere Informationen.

Screenshot: Artikel mit Kennzeichnungen für Titel, Einführung, Berechtigungen, Produktcallout, Abschnitt zu Konzepten, Abschnitt zu Prozeduren und Inhaltsverzeichnis

Titel

Titel beschreiben vollständig, worum es auf einer Seite geht und was jemand durch das Lesen der Seite lernen wird.

Titel können eine Herausforderung darstellen. Verwenden Sie diese allgemeinen Richtlinien, um klare, hilfreiche und beschreibende Titel zu formulieren. Die Richtlinien für jeden Inhaltstyp in diesem Artikel enthalten spezifischere Titelregeln.

Titel für alle Inhaltstypen

  • Titel beschreiben eindeutig, worum es auf einer Seite geht. Sie sind beschreibend und spezifisch.
    • Verwenden Sie beispielsweise „Durchsuchen von Aktionen im Workflow-Editor“.
    • Verwenden Sie beispielsweise „Beispiel für die Konfiguration von Codespaces“.
    • Vermeiden Sie Titel wie „Verwenden der Seitenleiste des Workflow-Editors“.
    • Vermeiden Sie Titel wie „Beispiel“.
  • Für Titel gelten strenge Längenbeschränkungen, sodass sie leicht zu verstehen sind (und auf der Website einfacher gerendert werden können):
    • Kategorietitel: 67 Zeichen und shortTitle 26 Zeichen
    • Titel für zugehörige Themen: 63 Zeichen und shortTitle 29 Zeichen
    • Artikeltitel: 80 Zeichen (nach Möglichkeit 60 Zeichen), und shortTitle 30 Zeichen (idealerweise 20 bis 25 Zeichen).
  • Die Groß- und Kleinschreibung in Titeln entspricht dem normalen Text.
    • Verwenden Sie: „Eine Commit-Mitteilung ändern“
    • Vermeiden Sie: „Eine Commit-Mitteilung Ändern“
  • Titel sind für einen Inhaltstyp konsistent. Sehen Sie sich die spezifischen Richtlinien für jeden Inhaltstyp an.
  • Titel sind allgemein genug, um bei Produktänderungen skaliert werden zu können, den gesamten Inhalt innerhalb des Artikels widerzuspiegeln oder Inhalte zu mehreren Produkten zu enthalten.
    • Verwenden Sie: „Abrechnungspläne von GitHub“
    • Vermeiden Sie „Abrechnungspläne für Benutzer- und Organisationskonten“.
  • Für Titel wird eine konsistente Terminologie verwendet.
    • Entwicklen und befolgen Sie Muster innerhalb einer Kategorie oder zu ähnlichen Themen.
  • Für Titel wird Terminologie aus dem Produkt selbst verwendet.
  • Formulieren Sie den Titel und die Einführung in einem Schritt.
    • Verwenden Sie die Einführung, um die im Titel vorgestellten Ideen weiter auszuführen.
    • Weitere Informationen finden Sie in der Anleitung zu Einführungen.
  • Wenn Sie Probleme beim Formulieren eines Titels haben, berücksichtigen Sie den Inhaltstyp. Manchmal deuten Probleme bei der Auswahl eines Titels darauf hin, dass ein anderer Inhaltstyp besser geeignet ist.
  • Überlegen Sie, wie der Titel in den Suchergebnissen für mehrere Produkte angezeigt wird.
    • Welche spezifischen Wörter müssen Sie in den Titel oder die Einführung aufnehmen, damit keine Missverständnisse hinsichtlich des Inhalts entstehen?
  • Überlegen Sie, wie der Titel in der Produktion aussehen wird.

Einführung

Oben auf jeder Seite gibt es eine Einführung, die den Kontext erläutert und Erwartungen weckt, sodass Leserinnen schnell entscheiden können, ob die Seite für sie relevant ist. Einführungen werden auch in Suchergebnissen angezeigt, um Kontextinformationen bereitzustellen, die Leserinnen bei der Auswahl eines Ergebnisses helfen.

Schreiben einer Einführung

  • Artikeleinführungen sind ein bis zwei Sätze lang.
  • Zugehörige Themen und Kategorieeinführungen umfassen einen Satz.
  • API-Referenzeinführungen sind einen Satz lang.
    • Die Einführung für eine API-Seite sollte das Feature definieren, damit deutlich wird, ob das Feature die Anforderungen der Benutzer*innen erfüllt, ohne den gesamten Artikel lesen zu müssen.
  • Einführungen enthalten eine allgemeine Zusammenfassung des Seiteninhalts und beschreiben die Idee des Titels etwas genauer.
    • Verwenden Sie verständliche Synonyme für die Wörter im Titel der Seite, um den Leser*innen zu helfen, den Zweck des Artikels zu verstehen. Vermeiden Sie nach Möglichkeit, Wörter aus dem Titel zu wiederholen.
  • Einführungen sind relativ allgemein formuliert, sodass sie bei zukünftigen Änderungen an den Inhalten auf der Seite skaliert werden können, ohne dass sie häufig aktualisiert werden müssen.
  • Im Sinne der Durchsuchbarkeit sollten Sie in der Einführung für das Thema Schlüsselwörter verwenden.
  • Wenn es für einen Begriff in der Einführung ein Akronym gibt, das an anderer Stelle im Artikel verwendet wird, erläutere das Akronym.
  • Einführungen umfassen in der Regel keine Berechtigungsinformationen für Aufgaben, die im Artikel enthalten sind.

Berechtigungsanweisungen

Jede Prozedur enthält Angaben zu Berechtigungen, die die Rolle erläutern, die zum Ausführen der in der Prozedur beschriebenen Aktion erforderlich ist. Dies hilft den Benutzer*innen zu verstehen, ob sie die Aufgabe abschließen können.

Gelegentlich ist es relevant, die erforderlichen Berechtigungen in konzeptionellen Inhalten zu erwähnen (insbesondere in eigenständigen konzeptuellen Artikeln). Stellen Sie sicher, dass die Angaben zu Berechtigungen auch in zusammenhängende Prozeduren einschließt (oder einen längeren Artikel schreibst, der den gesamten Inhalt kombiniert).

Formulieren von Angaben zu Berechtigungen

  • Wenn eine einzelne Berechtigungsgruppe für alle Prozeduren in einem Artikel gilt, verwende die permissions-Frontmatter.
  • Wenn ein Artikel mehrere Prozeduren enthält und unterschiedliche Berechtigungen gelten, fügen Sie vor jeder Prozedur unter jeder relevanten Überschrift Angaben zu Berechtigungen ein.
  • Fügen Sie keine Angaben zu Berechtigungen in die Einführung eines Artikels ein.
  • Es gibt Rollen auf verschiedenen Ebenen. Beziehen Sie sich nur auf die Rolle, die sich auf derselben Ebene wie die Aktion befindet. Beispielsweise benötigen Sie Administratorzugriff auf ein Repository (Rolle auf Repositoryebene), um geschützte Branches zu konfigurieren. Sie können Administratorzugriff auf ein Repository erhalten, indem Sie Organisationsbesitzer*in bist (Rolle auf Organisationsebene), aber die Rolle auf Repositoryebene bestimmt letztendlich, ob die Aktion möglich ist. Deshalb ist das die einzige Rolle, die in den Angaben zu Berechtigungen erwähnt werden sollte.
  • Sprache, die in Angaben zu Berechtigungen verwendet werden soll:
    • [KONTOROLLE] kann [AKTION].
    • Personen mit [FEATUREROLLE]-Zugriffsberechtigungen für [FEATURE] können [AKTION].
    • Vermeiden Sie Formulierungen wie „[KONTOROLLE] und Personen mit [FEATUREROLLE]-Zugriff für [FEATURE] können [AKTION]“.

Beispiele für Angaben zu Berechtigungen

Produktcallouts

Verwenden Sie den Produktcallout, wenn ein Feature nur in bestimmten Produkten verfügbar ist und diese Verfügbarkeit nicht allein durch die Versionsverwaltung vermittelt werden kann. Wenn beispielsweise ein Feature für GHEC und GHES verfügbar ist, können Sie Inhalte zum Feature nur für GHEC und GHES versionieren. Wenn ein Feature für Pro, Team, GHEC und GHES (aber nicht für Free) verfügbar ist, verwenden Sie einen Produktcallout, um diese Verfügbarkeit zu vermitteln.

Alle Produktcallouts werden als wiederverwendbare Elemente in gated-features gespeichert und in der YAML-Frontmatter für relevante Artikel hinzugefügt.

Schreiben von Produktcallouts

  • Produktcallouts folgen einem strengen Format, durch das das Feature und die darin enthaltenen Produkte eindeutig angegeben werden.
  • Produktcallouts enthalten auch einen Link zu „GitHub-Produkte“ und gelegentlich zu einem anderen relevanten Artikel.
  • Beispiele:
    • [Featurename] ist in [Produkt(e)] verfügbar. Weitere Informationen finden Sie unter „GitHub-Produkte“.
    • [Featurename] ist in öffentlichen Repositorys mit [kostenlose Produkte] und in öffentlichen und privaten Repositorys mit [kostenpflichtige Produkte] verfügbar. Weitere Informationen finden Sie unter „GitHub-Produkte“.

Beispiele für Artikel mit Produktcallouts

Überprüfen Sie die Quelldateien und gated-features, um zu sehen, wie Quellinhalte geschrieben werden.

Toolumschalter

Einige Artikel umfassen Inhalte, die je nachdem variieren, welches Tool zum Ausführen einer Aufgabe verwendet wird (z. B. GitHub CLI oder GitHub Desktop). Bei den meisten Inhalten sind dieselben konzeptionellen oder prozeduralen Informationen für mehrere Tools gültig. Wenn die einzige Möglichkeit, Informationen deutlich zu vermitteln, darin besteht, Inhalte nach Tool zu unterscheiden, verwende den Toolumschalter. Verwenden Sie den Toolumschalter nicht, um lediglich Beispiele in verschiedenen Sprachen anzuzeigen. Verwenden Sie den Toolumschalter nur, wenn sich die Aufgaben oder Konzepte in Abhängigkeit des verwendeten Tools ändern. Weitere Informationen findest du unter Erstellen von Toolumschaltern in Artikeln.

Inhaltsverzeichnis

Inhaltsverzeichnisse werden automatisch generiert. Weitere Informationen finden Sie unter Automatisch generierte Kurzverzeichnisse.

Konzeptionelle Inhalte

Konzeptionelle Inhalte helfen dabei, ein Thema zu verstehen oder mehr darüber zu erfahren. Weitere Informationen findest du unter „Konzeptioneller Inhaltstyp“ im Inhaltsmodell.

Referenzielle Inhalte

Referenzielle Inhalte bieten strukturierte Informationen im Zusammenhang mit der aktiven Verwendung eines Produkts oder Features. Weitere Informationen findest du unter „Referenzieller Inhaltstyp“ im Inhaltsmodell.

Voraussetzungen

Voraussetzungen sind Informationen, die Personen kennen müssen, bevor sie mit einer Prozedur fortfahren, damit sie vor Beginn der Aufgabe alle erforderlichen Komponenten vorbereiten können.

Formulieren von Voraussetzungen

  • Nenne die Voraussetzungen unmittelbar vor den nummerierten Schritten einer Prozedur.
  • Sie können eine Liste, einen Satz oder einen Absatz verwenden, um die Voraussetzungen zu erläutern.
  • In den folgenden Fällen können Sie auch einen separaten Abschnitt mit den Voraussetzungen verwenden:
    • Die Informationen zu den Voraussetzungen sind sehr wichtig und sollten nicht übersehen werden.
    • Es gibt mehrere Voraussetzungen.
  • Um wichtige Informationen zu Datenverlust oder destruktiven Aktionen zu wiederholen oder hervorzuheben, können Sie auch eine Warnung oder einen Gefahrenhinweis verwenden, um eine Voraussetzung zu vermitteln.

Titelrichtlinien für Voraussetzungen

  • Nutze im Fall eines separaten Abschnitts für die Voraussetzungen die Überschrift Prerequisites.

Beispiele für Artikel mit Abschnitten zu Voraussetzungen

Prozedurale Inhalte

Prozedurale Inhalte unterstützen Personen beim Abschließen von Aufgaben. Weitere Informationen findest du unter „Prozeduraler Inhaltstyp“ im Inhaltsmodell.

Inhalte zur Problembehandlung

Inhalte zur Problembehandlung helfen Benutzer*innen dabei, Fehler zu vermeiden oder zu beheben. Weitere Informationen findest du unter „Inhaltstyp zur Problembehandlung“ im Inhaltsmodell.

Nächste Schritte

Wenn ein Artikel einen Schritt in einem größeren Prozess beschreibt oder über einen logischen nächsten Schritt verfügt, den die meisten Personen ausführen möchten, schließe einen Abschnitt mit den nächsten Schritten ein. Du kannst Personen auf Artikel oder andere GitHub-Ressourcen verweisen.

Beispiele für Abschnitte der nächsten Schritte

## Next steps

- You can monitor self-hosted runners and troubleshoot common issues. See "Monitoring and troubleshooting self hosted runners."

- GitHub recommends that you review security considerations for self-hosted runner machines. See "Security hardening for GitHub Actions."

In diesem Beispiel aus „Erste Schritte mit selbstgehosteten Runnern für dein Unternehmen“ enthält der Abschnitt „Nächste Schritte“ Links zu Prozeduren, die durchgeführt werden müssen, nachdem man mit der Verwendung des im Artikel beschriebenen Features begonnen hat.

## Next steps

After your enterprise account is created, we recommend learning more about how enterprise accounts work and configuring settings and policies. Follow the "Get started with your enterprise account" learning path.

In diesem Beispiel aus „Erstellen eines Unternehmenskontos“ wird der nächste Schritt mit dem Ort verknüpft, an dem die meisten Personen, die gerade die Erstellung einer Enterprise-Konto abgeschlossen haben, wahrscheinlich als Nächstes fortfahren möchten.

Weitere Informationen

Wenn es zusätzliche Artikel gibt, die Personen bei der Durchführung ihrer Aufgabe unterstützen oder ihnen lehren, das im aktuellen Artikel beschriebene Thema zu verwenden, füge sie in einen weiteren Leseabschnitt ein. Füge nur Links zu Artikeln hinzu, die noch nicht im Inhalt des Artikels verknüpft wurden.

Füge nur Links hinzu, die Personen bei der betreffenden Aufgabe oder dem Thema unterstützen. Es ist besser, fokussiert zu sein und Personen wertvolle Ressourcen zur Verfügung zu stellen, als ihnen jeden möglichen Link anzubieten.

Formatieren Sie die Abschnitte mit weiteren Informationsquellen mithilfe von ungeordneten Listen. Informationen zum Erstellen von Links findest du unter Styleguide.

Titel und Format für Abschnitte mit weiteren Informationsquellen

## Further reading
- "[Article title](article-URL)"
- [External resource title](external-resource-URL) in External Resource Name