Informationen zum Inhaltsmodell

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

In diesem Artikel

Unser Inhaltsmodell erläutert den Zweck jeder Art von Inhalten, die wir erstellen GitHub Docs, und was beim Schreiben oder Aktualisieren eines Artikels eingeschlossen werden soll. Wir verwenden ein Inhaltsmodell, um sicherzustellen, dass unsere Inhalte konsistent, klar und umfassend kommunizieren die Informationen, mit GitHubdenen die Menschen ihre Ziele erreichen müssen.

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, mentale Modelle der Dokumentation zu bilden und zu verstehen, wie sie die benötigten Informationen finden, wenn sie im Laufe der Zeit zurückkehren GitHub Docs . Es ist auch effizienter, konsistente Inhalte zu verwalten und zu aktualisieren, wodurch es einfacher und schneller ist, zu Dokumenten beizutragen, unabhängig davon, ob Sie ein Open Source Mitwirkender sind, der Ihren ersten Commit oder einen Autor für die Mitarbeiter dokumentiert, das GitHub ein ganzes neues Produkt dokumentiert.

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 um die Balance zwischen spezifischen Gruppierungen, die den Leuten helfen, das zu finden, wonach sie suchen, und dem Limit der Schichten, durch die die Leute navigieren müssen. Tiefe Hierarchien mit vielen verschachtelten Themen können es schwierig machen, bestimmte Artikel zu finden. Breite Hierarchien mit vielen Kategorien oder Artikeln auf der gleichen Ebene erschweren die Evaluierung und die Entscheidung, was man auswählen möchte.

Inhalt der Startseite

Die GitHub Docs Homepage , docs.github.com, hebt die wichtigsten Themen hervor, die die Menschen finden möchten. 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. Inhalte auf der Homepage sind in Bezug auf GitHub Konzepte und Praktiken organisiert. Die Gruppe "CI/CD und DevOps" enthält z. B. Dokumentensätze auf oberster Ebene für GitHub Actions, GitHub Packagesund GitHub Pages.

Hinzufügen einer Dokumentationsgruppe zur Startseite

Das Ziel der Homepage ist es, Personen dabei zu helfen, Informationen zu dem GitHub Feature oder Produkt zu finden, über das sie erfahren 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 Ausgangspunkt für die Verwendung eines GitHub Produkts oder Features dient, kann sie der Homepage hinzugefügt werden.

Allgemeine Dokumentationsgruppe

Dokumente auf oberster Ebene sind um ein Produkt, ein Feature oder einen GitHub zentralen Workflow herum organisiert. Alle Dokumentensätze der obersten Ebene 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.

  • Dokumentenmappen auf oberster Ebene sind von ungefähr gleicher Bedeutung füreinander (jede ist auf ein Produkt oder hauptfeature GitHub zentriert).
  • Die meisten allgemeinen Dokumentationsgruppen weisen ein Startseitenlayout auf, es sei denn, es handelt sich um eine wichtige Ausnahme. Das Site-Richtlinien Dokumentset hat zum Beispiel keine Anleitungen oder Verfahrensartikel wie andere Dokumentsets und verwendet daher auch kein Landing Page Layout.
  • Dokumentsets der obersten Ebene können eine Mischung aus Kategorien, Zuordnungsthemen 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 Map-Themen enthalten, um den Inhalt in spezifischere Benutzer-Reisen 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 Zuordnungsthemen 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.

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

Allgemein gilt: Vermeide es, ein Zuordnungsthema innerhalb eines Zuordnungsthemas zu haben, es sei denn, es ist der beste Weg, um eine bestimmte Anforderung des Benutzers 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
  • Die Titel von Zuordnungsthemen müssen 63 Zeichen oder kürzer sein und shortTitle weniger als 30 Zeichen enthalten.
  • 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– während 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.