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 eines Artikels mit gekennzeichnetem Titel, Einführung, Berechtigungen, Produktaufruf, konzeptionellem Abschnitt, prozeduralem Abschnitt und Inhaltsverzeichnis.

Titel

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

Die Titel können herausfordernd sein. 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 das „Beispiel für die Konfiguration eines Codespace“.
    • Vermeiden Sie die Verwendung 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).
  • Titel verwenden die Satzschrift.
    • Verwenden Sie 'Ändern einer Commit-Nachricht'
    • Vermeiden Sie: „Eine Commit-Nachricht ä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.
    • Verwendung von: "GitHub's Abrechnungsplänen"
    • 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 wir in den Titel oder die Einführung aufnehmen, damit es nicht mit Inhalten zu einem anderen Produkt verwechselt wird?
  • Überlegen Sie, wie der Titel in der Produktion aussehen wird.

Einführung

Jede Seite und jeder Artikel enthält eine Einführung, die beschreibt, worum es geht. Der Text, den wir für Einführungen verwenden, wird auch in Suchergebnissen angezeigt und macht sie für SEO wichtig.

So schreiben Sie eine Einführung

  • Intros sollten prägnant sein, idealerweise ein Satz lang.
  • Einführungen helfen Menschen dabei, herauszufinden, ob sie am richtigen Ort für ihre Bedürfnisse sind. Informieren Sie den Benutzer darüber, welchen Mehrwert Sie bieten, indem Sie Wörter verwenden, die er verwenden und nach denen er suchen würde.
  • Einführungen sind auch eine Einladung, weiterzulesen. Eine gute Einführung versichert dem Leser, dass ihre Zeit gut aufgewendet wird.
  • Wenn ein wichtiger Begriff ein verwandtes Akronym aufweist, das in der Regel an seiner Stelle verwendet wird, schließen Sie das Akronym in die Einführung ein. (Beispiel: Suchmaschinenoptimierung und SEO.)
  • Überprüfen Sie schließlich Ihre Einführung, um sicherzustellen, dass sie suchmaschinenfreundlich ist, indem Sie relevante Schlüsselwörter und Ausdrücke einschließen.

Berechtigungsaussagen

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). Stellt sicher, dass die Angaben zu Berechtigungen auch in relevante Verfahren eingefügt werden (oder einen längeren Artikel schreiben, der den gesamten Inhalt kombiniert).

Wie man eine Berechtigungserklärung verfasst

  • 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:
    • Personen mit [KONTOROLLE]
    • [KONTOROLLE] kann [AKTION].
    • Personen mit [FEATUREROLLE]-Zugriffsberechtigungen für [FEATURE] können [AKTION].
    • Vermeiden Sie die Verwendung von [KONTOROLLE] und Personen, die Zugriff auf [FEATUREROLLE] für [FEATURE] haben, können [AKTION] durchführen.

Weitere Informationen zum Formatieren von Berechtigungsanweisungen findest du unter Stil-Leitfaden.

Produkthinweise

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.
  • Produktmerkmale können Links zu Artikeln enthalten, die Benutzern direkt helfen, zu verstehen, wer die Funktion nutzen kann. Diese Links können Inlinelinks zu den spezifischen Produkten oder GitHub Plänen sein, die erforderlich sind.
  • Beispiele:
    • [Featurename] ist in [Produkt(e)] verfügbar.
    • [Featurename] ist in öffentlichen Repositorys mit [kostenlose Produkte] und in öffentlichen und privaten Repositorys mit [kostenpflichtige Produkte] verfügbar.

Beispiele für Artikel mit Produkthinweisen

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

Werkzeugwechsler

Einige Artikel enthalten Inhalte, die sich je nach verwendetem Tool, wie zum Beispiel GitHub CLI oder GitHub Desktop, unterscheiden, um eine Aufgabe auszuführen. 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 finden Sie unter Erstellen von Toolumschaltern in Artikeln.

Inhaltsverzeichnis

Inhaltsverzeichnisse werden automatisch generiert. Weitere Informationen findest du 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

  • Bei einem separaten Abschnitt, verwenden Sie eine Überschrift namens Prerequisites.

Beispiele für Artikel mit Abschnitten zu Voraussetzungen

  •         [AUTOTITLE](/enterprise-server@latest/admin/installation/installing-github-enterprise-server-on-aws)

  •         [AUTOTITLE](/enterprise-server@latest/admin/configuration/enabling-subdomain-isolation)

Prozedurale Inhalte

Prozedurale Inhalte unterstützen Personen beim Abschließen von Aufgaben. Weitere Informationen findest du unter Vorgehensweise: 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. Sie können Personen mit Artikeln oder anderen GitHub Ressourcen verknüpfen.

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 Ihr 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.

Weiterführende Lektüre

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 „Weiterführende Informationen“ mithilfe von ungeordneten Listen. Informationen zum Erstellen von Links findest du unter Stil-Leitfaden.

Titel und Format für weiterführende Literaturabschnitte

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