Bewährte Methoden für GitHub-Dokumente

Orientieren Sie sich an diesen bewährten Methoden, um Dokumente zu erstellen, die benutzerfreundlich und leicht verständlich sind.

In diesem Artikel

Informationen zur GitHub-Dokumentation

Bei GitHub sind wir bestrebt, eine Dokumentation zu erstellen, die genau, wertvoll, inklusiv, zugänglich und einfach zu verwenden ist.

Bevor du einen Beitrag zu GitHub Docs leistest, nimm dir einen Moment Zeit, um dich mit der Dokumentationsphilosophie, den Grundlagen und den Prinzipien der Inhaltsgestaltung von GitHub vertraut zu machen:

Bewährte Methoden zum Schreiben von GitHub-Dokumentation

Unabhängig davon, ob Sie einen neuen Artikel erstellen oder einen bestehenden aktualisieren möchten, sollten Sie beim Schreiben für GitHub Docs die folgenden Richtlinien beachten:

Die Inhalte an den Benutzeranforderungen ausrichten

Bevor Sie mit dem Schreiben beginnen, sollten Sie sich darüber im Klaren sein, für wen Sie schreiben, welche Ziele dieser Personenkreis verfolgt, auf welche Kernaufgaben oder Konzepte der Artikel abzielt und welche Art von Text Sie schreiben wollen.

Festlegen der Zielgruppe

  • Wer wird diese Inhalte lesen?
  • Was möchte er oder sie damit erreichen?

Definieren des Hauptziels

  • Was sollte jemand nach dem Lesen dieses Artikels tun können oder verstehen? Wählen Sie eine oder zwei Aufgaben oder Konzepte, die im Inhalt besprochen werden sollen.
  • Wenn der Text zusätzliche Aufgaben, Konzepte oder Informationen enthält, die nicht unbedingt notwendig sind, sollten Sie in Betracht ziehen, diese weiter unten im Artikel zu platzieren, sie in einen anderen Artikel zu verschieben oder ganz wegzulassen.

Inhaltstyp festlegen

Legen Sie anhand der Zielgruppe und des Hauptzwecks des Inhalts fest, welche Art von Text Sie schreiben werden. GitHub Docs verwendet die folgenden Inhaltstypen:

Verwenden Sie z. B. den konzeptionellen Inhaltstyp, um den Lesern die Grundlagen einer Funktion oder eines Themas näher zu bringen und ihnen zu zeigen, wie sie damit ihre Ziele erreichen können. Verwenden Sie den prozeduralen Inhaltstyp, um Ihrer Zielgruppe dabei zu helfen, eine bestimmte Aufgabe von Anfang bis Ende zu erledigen.

Inhalte so strukturieren, dass sie gut lesbar sind

Nutzen Sie die folgenden bewährten Methoden, um den Inhalt zu strukturieren. Beim Hinzufügen von Inhalten zu einem bestehenden Artikel sollten Sie sich möglichst an die bestehende Struktur halten.

  • Geben Sie zu Beginn den Kontext an. Legen Sie das Thema fest und erklären Sie, welche Bedeutung es für den Leser hat.
  • Bringen Sie den Inhalt in eine logische Reihenfolge, strukturiert nach Wichtigkeit und Relevanz. Ordnen Sie die Informationen nach deren Priorität und in der Reihenfolge, in der die Benutzer sie benötigen.
  • Vermeiden Sie lange Sätze und Absätze.
    • Führen Sie einen Begriff nach dem anderen ein.
    • Verwerten Sie eine Idee pro Absatz.
    • Verwerten Sie eine Idee pro Satz.
  • Betonen Sie die wichtigsten Informationen.
    • Beginnen Sie jeden Satz oder Absatz mit den wichtigsten Worten und Schlussfolgerungen.
    • Nennen Sie bei der Erläuterung eines Konzepts gleich zu Beginn die Schlussfolgerung und erläutern Sie es dann ausführlicher. (Diese Vorgehensweise wird manchmal als „invertierte Pyramide“ bezeichnet.)
    • Wenn Sie ein komplexes Thema erläutern, sollten Sie den Lesern zunächst die grundlegenden Informationen zur Verfügung stellen und erst später im Artikel auf die Einzelheiten eingehen.
  • Verwenden Sie aussagekräftige Unterüberschriften. Gliedern Sie zusammenhängende Absätze in Abschnitte. Versehen Sie jeden Abschnitt mit einer Unterüberschrift, die eindeutig ist und den Inhalt genau beschreibt.
  • Erwägen Sie die Verwendung von seiteninternen Links bei längeren Inhalten. So können die Leser zu den Bereichen springen, die sie interessieren, und Inhalte überspringen, die für sie nicht von Bedeutung sind.

Beim Schreiben auf die Lesbarkeit achten

Machen Sie es vielbeschäftigten Nutzern leicht, den Text zu lesen und zu verstehen.

  • Verwenden Sie einfache Sprache. Verwenden Sie gebräuchliche, alltägliche Wörter und vermeiden Sie Fachjargon, wenn möglich. Begriffe, die Entwicklern gut bekannt sind, sind in Ordnung. Gehen Sie aber nicht davon aus, dass der Leser die Funktionsweise von GitHub im Detail kennt.
  • Verwenden Sie Aktivkonstruktionen
  • Fassen Sie sich kurz.
    • Formulieren Sie einfache, kurze Sätze.
    • Vermeiden Sie komplexe Sätze, die mehrere Konzepte enthalten.
    • Verzichten Sie auf unnötige Details.

Verwandte Informationen finden Sie unter „Sprache und Tonfall“ in Styleguide und Schreiben von zu übersetzenden Inhalten.

So formatieren, dass die Dokumente überflogen werden können

Die meisten Leser werden Artikel nicht von Anfang bis Ende lesen. Stattdessen überfliegen sie entweder die Seite, um bestimmte Informationen zu finden, oder werfen einen kurzen Blick auf die Seite, um sich einen allgemeinen Überblick über die Konzepte zu verschaffen.

Beim Überfliegen von Inhalten überspringen die Leser große Textblöcke. Du suchst nach Elementen, die mit deiner Aufgabe zusammenhängen oder die auf der Seite hervorstechen, wie Überschriften, Warnhinweise, Listen, Tabellen, Codeblöcke, Bilder und die ersten Worte in jedem Abschnitt.

Sobald der Artikel einen klar definierten Zweck und eine klare Struktur hat, können Sie die folgenden Formatierungstechniken anwenden, um den Inhalt für das Überfliegen zu optimieren. Diese Techniken können auch dazu beitragen, Inhalte für alle Leser verständlicher zu machen.

  • Verwenden Sie Texthervorhebungen wie Fettdruck und Hyperlinks, um die Aufmerksamkeit auf die wichtigsten Punkte zu lenken. Gehen Sie sparsam mit Texthervorhebungen um. Heben Sie nicht mehr als 10 % des gesamten Texts eines Artikels hervor.
  • Verwenden Sie Formatierungselemente, um den Inhalt zu gliedern und Platz auf der Seite zu schaffen. Zum Beispiel:
    • Aufzählungen (mit optionalen Unterüberschriften)
    • Nummerierte Listen
    • Warnhinweise
    • Tabellen
    • Visuals
    • Codeblöcke und Codeanmerkungen

Weiterführende Themen