Enterprise Server 3.15 ist derzeit als Release Candidate verfügbar.

Informationen zum Inhaltsmodell

Das Inhaltsmodell beschreibt die Struktur und die Inhaltstypen, die wir veröffentlichen.

In diesem Artikel

Das Inhaltsmodell erläutert den Zweck der einzelnen Inhaltstypen, die wir in GitHub Docs erstellen, und was beim Schreiben oder Aktualisieren eines Artikels enthalten sein soll. Wir verwenden ein Inhaltsmodell, um sicherzustellen, dass unsere Inhalte konsistent, klar und umfassend die Informationen kommunizieren, die die Benutzer*innen benötigen, um ihre Ziele mit GitHub zu erreichen.

Wir verwenden diese Typen für alle Dokumentationsgruppen, um eine konsistente Nutzung zu ermöglichen. Jeder Inhaltstyp gilt für jedes Produkt oder jede Zielgruppe. Unsere Inhaltstypen werden im Laufe der Zeit weiterentwickelt, und wir fügen bei Bedarf neue Typen hinzu. Wir veröffentlichen nur Inhalte, die dem Modell entsprechen.

Konsistenz hilft Menschen dabei, gedankliche Modelle der Dokumentation zu erstellen und zu verstehen, wie sie die benötigten Informationen finden können, wenn sie GitHub Docs erneut nutzen. Es ist auch effizienter, konsistente Inhalte zu verwalten und zu aktualisieren, da Benutzerinnen einfacher und schneller zu Dokumentationen beitragen können, unabhängig davon, ob sie Open-Source-Mitwirkende sind und zum ersten Mal committen oder Autorinnen für das GitHub-Team sind, die ein gesamtes neues Produkt dokumentieren.

Inhaltsstruktur

Die Dokumentation ist auf unserer Website in mehreren Hierarchieebenen organisiert.

  • Allgemeine Dokumentationsgruppe
    • Kategorien
      • Zugehörige Themen
        • Artikel
      • Artikel
    • Artikel

Bei der Organisation von Inhalten geht es darum, eine Balance zu finden zwischen spezifischen Gruppierungen, die es den Nutzern erleichtern, das zu finden, was sie suchen, und der Begrenzung der Hierarchieebenen, durch die die Nutzer navigieren müssen. Tiefe Hierarchien mit vielen zusammen geschachtelten zugehörigen Themen können es schwierig machen, bestimmte Artikel zu finden. Breite Hierarchien mit vielen Kategorien oder Artikeln auf der gleichen Ebene erschweren die Bewertung und die Entscheidung bei einer Auswahl.

Inhalt der Startseite

Auf der GitHub Docs-Startseite (docs.github.com) werden die wichtigsten Themen für Benutzer*innen hervorgehoben. Wir beschränken die Anzahl der Dokumentationsgruppen auf der Startseite, sodass die Informationen leicht zugänglich sind und die Seite nicht überladen wirkt.

Die Startseite enthält alle allgemeinen Dokumentationsgruppen und einige Kategorien. Die Inhalte auf der Startseite sind um GitHub-Konzepte und -Methoden herum organisiert. Die Gruppe „CI/CD und DevOps“ enthält beispielsweise allgemeine Dokumentationsgruppen für GitHub Actions, GitHub Packages und GitHub Pages.

Hinzufügen einer Dokumentationsgruppe zur Startseite

Das Ziel der Startseite besteht darin, Personen dabei zu helfen, Informationen über das GitHub-Feature oder das Produkt zu finden, über das sie sich informieren möchten. Jedes der Startseite hinzugefügte Element erschwert die Auffindbarkeit jedes anderen Elements, sodass wir die Anzahl der auf der Startseite enthaltenen Dokumentationsgruppen begrenzen.

Wenn eine neue allgemeine Dokumentationsgruppe erstellt wird, wird diese der Startseite hinzugefügt.

Wenn eine Kategorie als Startpunkt für die Verwendung eines GitHub-Produkts oder -Features dient, kann sie der Startseite hinzugefügt werden.

Beispielsweise sind unter der Gruppe „Sicherheit“ auf der Startseite zusätzlich zur allgemeinen Dokumentationsgruppe Codesicherheit die Kategorien Lieferkettensicherheit, Sicherheitsempfehlungen, Dependabot, Code scanning und Secret scanning enthalten, da jede dieser Kategorien einen Einstiegspunkt für GitHub-Produkte und -Features darstellt. Die Sicherheitsübersicht ist auf der Startseite nicht enthalten, da sie zusätzliche Informationen für die Verwendung von Codesicherheitsprodukten bietet und keine Einführung in ein Produkt oder Feature darstellt.

Allgemeine Dokumentationsgruppe

Allgemeine Dokumentationsgruppen sind um ein GitHub-Produkt, -Feature oder -Kernworkflow herum organisiert. Alle allgemeinen Dokumentationsgruppen werden auf der GitHub Docs-Startseite angezeigt. Sie sollten nur dann eine allgemeine Dokumentationsgruppe erstellen, wenn in der neuen Dokumentationsgruppe umfassende Inhalte enthalten sind, mehrere Kategorien in zugehörige Themen unterteilt werden können und das Thema übergreifend für Produkte, Features oder Kontotypen gilt. Wenn die Inhalte in eine vorhandene allgemeine Dokumentationsgruppe passen könnten, gehören sie wahrscheinlich in diese vorhandene Dokumentationsgruppe.

  • Alle allgemeinen Dokumentationsgruppen sind ungefähr gleich wichtig (Fokus jeder Gruppe liegt auf einem GitHub-Produkt oder -Hauptfeature).
  • Die meisten allgemeinen Dokumentationsgruppen weisen ein Startseitenlayout auf, es sei denn, es handelt sich um eine wichtige Ausnahme. Die Dokumentationsgruppe Website-Richtlinie enthält beispielsweise keine Anleitungen oder prozeduralen Artikel wie andere Dokumentationsgruppen, weshalb kein Startseitenlayout verwendet wird.
  • Dokumente auf oberster Ebene können eine Mischung aus Kategorien, zugehörigen Themen oder Artikeln enthalten.

Titel für allgemeine Dokumentationsgruppen

Category

Kategorien sind um ein Feature oder eine bestimmte Gruppe von Aufgaben in einer allgemeinen Dokumentationsgruppe herum organisiert, die auf Produktentwürfe ausgerichtet ist. Der Bereich einer Kategorie ist so begrenzt, dass der Inhalt verwaltbar ist und nicht zu umfassend wird. Einige Kategorien werden auf der Startseite angezeigt.

  • Kategorien beginnen oft spezifisch und wachsen mit dem Produkt.
  • Kategorien können zugehörige Themen enthalten, um Inhalte nach spezifischeren User Journeys oder Aufgaben zu unterteilen.
  • Verwenden Sie lange prozedurale Artikel, um verwandte Inhaltsblöcke zu gruppieren und Artikel innerhalb der Kategorie zu optimieren.
  • Wenn Kategorien mehr als zehn Artikel umfassen, sollten Sie den Inhalt in zugehörige Themen oder zusätzliche Kategorien unterteilen.
  • Kategorien können eine Mischung aus zugehörigen Themen oder Artikeln enthalten.

Titel für Kategorien

Einführungen für Kategorien

Alle Kategorien umfassen Einführungen. Einführungen sollten einen Satz lang und allgemein genug formuliert sein, um bei zukünftigen Produktänderungen skaliert werden zu können. Wenn Sie die Struktur einer Kategorie erheblich ändern, überprüfen Sie die Einführung auf erforderliche Aktualisierungen.

Zugehörige Themen

Zugehörige Themen bieten eine Einführung in einen Abschnitt einer Kategorie, indem Artikel innerhalb einer Kategorie um spezifischere Workflows oder Themen gruppiert werden, die Teil der allgemeineren Aufgabe der Kategorie sind.

Zugehörige Themen umfassen mindestens zwei Artikel. Wenn zugehörige Themen mehr als acht Artikel umfassen, kann es hilfreich sein, den Inhalt in spezifischere zugehörige Themen aufzuteilen.

Vermeiden Sie im Allgemeinen, ein zugehöriges Thema in einem zugehörigen Thema zu verwenden, es sei denn, es ist die beste Möglichkeit, einen bestimmten Benutzerbedarf zu erfüllen.

Titel für zugehörige Themen

  • Aufgabenbasiert (beginnt mit einem Gerundium)
  • Beschreibung einer spezifischeren Aufgabe innerhalb eines allgemeineren Workflows der Kategorie, in der sie sich befindet
  • Allgemein genug, um bei zukünftigen Ergänzungen des Produkts skaliert werden zu können
  • Titel für zugehörige Themen dürfen maximal 63 Zeichen lang sein, und der shortTitle muss weniger als 30 Zeichen aufweisen.
  • Beispiele

Einführungen für zugehörige Themen

Alle zugehörigen Themen umfassen Einführungen. Einführungen sollten einen Satz lang und allgemein genug formuliert sein, um bei zukünftigen Produktänderungen skaliert werden zu können. Wenn Sie Artikel in einem zugehörigen Thema hinzufügen oder entfernen, überprüfen Sie dessen Einführung auf erforderliche Aktualisierungen.

Artikel

Ein Artikel ist die grundlegende Inhaltseinheit für GitHub Docs. Obwohl wir mehrere Inhaltstypen verwenden, werden sie alle als Artikel veröffentlicht. Jeder Inhaltstyp hat seinen eigenen Zweck, sein eigenes Format und seine eigene Struktur, aber wir verwenden Standardelemente in jedem Artikeltyp (z. B. Einführungen), um sicherzustellen, dass Artikel eine konsistente Nutzung bieten.

Inhaltsreihenfolge

Wir organisieren Inhalte vorhersagbar in Kategorien, zugehörigen Themen und Artikeln. Von der allgemeinen Anwendbarkeit bis hin zu den spezifischen, eingrenzenden oder erweiterten Informationen, gilt diese Reihenfolge:

  • Konzeptionelle Inhalte
  • Referenzielle Inhalte
  • Prozedurale Inhalte zum Aktivieren eines Features oder einer Einstellung
  • Prozedurale Inhalte zur Verwendung eines Features
  • Prozedurale Inhalte zum Verwalten eines Features oder einer Einstellung
  • Prozedurale Inhalte zum Deaktivieren eines Features oder einer Einstellung
  • Prozedurale Inhalte zu destruktiven Handlungen (z. B. Löschung)
  • Informationen zur Problembehandlung

Wiederverwenden von Inhalten

Wir verwenden wiederverwendbare und variable Zeichenfolgen, um denselben Inhaltsabschnitt (z. B. einen Prozedurschritt oder einen konzeptionellen Absatz) an mehreren Stellen zu verwenden. In der Regel werden lange Artikelabschnitte nicht ohne einen bestimmten Grund wiederverwendet. Wenn ein ganzer Abschnitt eines Artikels in mehr als einem Artikel relevant sein kann, sieh dir den Zweck beider Artikel an. Gibt es eine Möglichkeit, einen einzelnen Artikel in Langform zu erstellen? Sehen Sie sich die Inhaltsmodelle an, um die bestmögliche Positionierung für die Informationen zu ermitteln, und fügen Sie im anderen Artikel einen Link zu diesem Inhalt ein.