Inhalt eines GitHub-Docs-Artikels

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.

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

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. Intros werden auch in Suchergebnissen angezeigt, um Kontextinformationen bereitzustellen, die den Leserinnen dabei helfen, ein Ergebnis auszuwählen.

So schreiben Sie eine Einführung

• Artikeleinführungen sind ein bis zwei Sätze lang.
• Themenkarten und Kategorieeinführungen bestehen aus einem 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 entwickeln die im Titel präsentierte Idee mit weiteren Details.
  • 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 bleiben relativ zeitlos und sind 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.
• Damit die Seite leichter gefunden werden kann, sollten Sie in der Einführung Schlüsselwörter zum Thema der Seite 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 enthalten in der Regel keine Genehmigungen für Aufgaben, die im Artikel erwähnt sind.

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. Bei diesen Links kann es sich um Inline-Links zu den spezifischen Produkten oder erforderlichen GitHub-Plänen handeln.
• 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 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 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 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 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