Mitwirken an der SQL Server-Dokumentation

  • Artikel

Gilt für:SQL ServerAzure SQL-DatenbankAzure Synapse AnalyticsAnalytics Platform System (PDW)

An der SQL Server-Dokumentation kann jeder mitwirken. Beispielsweise können Rechtschreibfehler korrigiert, genauere Erklärungen vorgeschlagen und die technische Richtigkeit geprüft werden. In diesem Artikel werden die ersten Schritte hierfür beschrieben.

Wenn Sie zur Dokumentation beitragen möchten, stehen Ihnen zwei Hauptworkflows zur Verfügung:

Workflow BESCHREIBUNG
Bearbeiten von Inhalten im Browser Geeignet für kleinere Bearbeitungen eines Artikels
Lokales Bearbeiten von Inhalten mit Tools Geeignet für komplexere Bearbeitungen in mehreren Artikeln und bei häufigen Beiträgen.

Alle öffentlichen Beiträge werden vom SQL-Inhaltsteam auf technische Richtigkeit und Konsistenz geprüft.

Bearbeiten von Inhalten im Browser

Sie können im Browser einfache Änderungen an SQL Server-Inhalten vornehmen und diese dann an Microsoft übermitteln. Weitere Informationen finden Sie im Leitfaden für Mitwirkende: Übersicht.

Die folgenden Schritte fassen den Prozess zusammen:

  1. Wählen Sie auf der Seite, zu der Sie Feedback übermitteln möchten, oben rechts den Link Bearbeiten aus.
  2. Wählen Sie auf der nächsten Seite oben rechts das Symbol Stift aus.
  3. Nehmen Sie auf der nächsten Seite im Textfenster Datei bearbeiten Ihre Änderungen direkt an dem Text vor, den Sie ändern möchten. Wenn Sie Hilfe beim Formatieren des neuen oder geänderten Texts benötigen, sehen Sie sich den „Spickzettel“ zum Markdown an.
  4. Nachdem Sie Ihre Änderungen vorgenommen haben, gehen Sie unter Änderungen vornehmen folgendermaßen vor:
    1. Geben Sie im ersten Textfeld eine kurze Beschreibung der Änderung ein, die Sie vorgenommen haben.
    2. Geben Sie im Feld Eine optionale erweiterte Beschreibung hinzufügen eine kurze Erläuterung Ihrer Änderung an.
  5. Wählen Sie Dateiänderung vorschlagen aus.
  6. Wählen Sie auf der Seite Änderungen werden verglichen die Option Pull Request erstellen aus.
  7. Wählen Sie auf der Seite Pull Request öffnen die Option Pull Request erstellen aus.

Die folgende GIF-Datei veranschaulicht den gesamten Ablauf zur Übermittlung von Änderungen in Ihrem Browser:

SQL-Dokumentation bearbeiten

Lokales Bearbeiten von Inhalten mit Tools

Eine weitere Bearbeitungsoption besteht darin, das sql-docs- oder azure-docs-Repository zu forken und es lokal auf dem Computer zu klonen. Anschließend können Sie mithilfe eines Markdown-Editors und eines Git-Clients die Änderungen übermitteln. Dieser Workflow eignet sich für Bearbeitungen, die komplexer sind oder mehrere Dateien betreffen. Er ist auch gut für häufige Mitwirkende zu Microsoft-technischen Dokumentationen geeignet.

Weitere Informationen zu dieser Bearbeitungsoption finden Sie in den folgenden Artikeln:

Wenn Sie einen Pull Request mit umfassenden Änderungen an der Dokumentation einreichen, wird in GitHub ein Kommentar angezeigt, in dem Sie aufgefordert werden, online eine Lizenzvereinbarung für Mitwirkende zu übermitteln. Sie müssen dieses Onlineformular ausfüllen, damit Ihr Pull Request akzeptiert wird.

Erkennung

Nachdem Ihre Änderungen akzeptiert wurden, werden Sie am Anfang des Artikels als Mitwirkender genannt.

Nennung als Mitwirkender bei Einreichung von Inhaltsänderungen

Übersicht über sql-docs

Dieser Abschnitt enthält zusätzliche Hinweise zur Arbeit mit dem sql-docs-Repository.

Wichtig

Diese beziehen sich ausschließlich auf sql-docs. Wenn Sie stattdessen einen SQL-Artikel der Azure-Dokumentation bearbeiten, finden Sie auf GitHub in der Infodatei des azure-docs-Repositorys weitere Informationen.

Zur Organisation von Inhalten werden im sql-docs-Repository die folgenden Standardordner verwendet:

Ordner BESCHREIBUNG
docs Enthält alle veröffentlichten SQL Server-Inhalte. In Unterordnern werden verschiedene Inhaltsbereiche organisiert.
docs/includes Enthält Includedateien. Diese Dateien bestehen aus Inhaltsblöcken, die in ein oder mehrere Artikel aufgenommen werden können.
./media Jeder Ordner kann über einen media-Unterordner für Artikelbilder verfügen. Der media-Ordner enthält wiederum Unterordner mit denselben Namen der Artikel, in denen die Bilder angezeigt werden. Bei den Bildern sollte es sich um PNG-Dateien handeln, deren Dateinamen aus Kleinbuchstaben bestehen und keine Leerzeichen enthalten.
TOC.MD Eine Inhaltsverzeichnisdatei. In jedem Unterordner kann eine TOC.MD-Datei verwendet werden.

applies-to-Includedateien

In jedem SQL Server-Artikel befindet sich nach dem Titel ein Verweis auf die applies-to-Includedatei. Damit wird angegeben, auf welche Bereiche oder Versionen von SQL Server sich der Artikel bezieht.

Im folgenden Markdown-Beispiel wird die Includedatei applies-to-version/sql-asdb-asa-pdw.md abgerufen.

[!INCLUDE[SQL Server Azure SQL Database Synapse Analytics PDW](../includes/applies-to-version/sql-asdb-asdbmi-asa-pdw.md)]

Dadurch wird der folgende Text am Anfang des Artikels angezeigt:

applies-to-Text

Mit den folgenden Tipps finden Sie die richtige applies-to-Includedatei für Ihren Artikel:

  • Eine Liste häufig verwendeter Includedateien finden Sie unter SQL Server-Includedateien für die Versionsverwaltung und „Applies-to“.
  • Suchen Sie nach anderen Artikeln, in denen es um dasselbe Feature oder um eine vergleichbare Aufgabe geht. Wenn Sie diese Artikel bearbeiten, können Sie das Markdown-Element für den Link zur applies-to-Includedatei kopieren. Dabei können Sie die Bearbeitung abbrechen, ohne die Änderungen zu senden.
  • Durchsuchen Sie das Verzeichnis docs/includes nach Dateien, die den Text „applies-to“ enthalten. Über die Schaltfläche Find (Suchen) können Sie in GitHub die Ergebnisse schnell filtern. Wählen Sie die Datei aus, um festzustellen, wie sie gerendert wird.
  • Beachten Sie die Namenskonvention. Wenn der Name mehrmals den Buchstaben „x“ enthält, ist dieser vermutlich ein Platzhalter, der darauf hinweist, dass ein bestimmter Dienst nicht unterstützt wird. Durch appliesto-xx-xxxx-asdw-xxx-md.md wird beispielsweise angegeben, dass ausschließlich Azure Synapse Analytics unterstützt wird, da nur die Zeichenfolge asdw vorhanden ist. Die anderen Felder enthalten hingegen nur den Buchstaben „x“.
  • In einigen Includedateien werden Versionsnummern wie tsql-appliesto-ss2017-xxxx-xxxx-xxx-md.md angegeben. Verwenden Sie diese Includedateien nur, wenn Sie wissen, dass dieses Feature mit einer bestimmten Version von SQL Server eingeführt wurde.

Ressourcen für Mitwirkende

Tipp

Wenn Sie nicht Feedback zur Dokumentation, sondern zu einem SQL Server-Produkt geben möchten, können Sie die hierfür eingerichtete Seite nutzen.

Nächste Schritte

Auf GitHub können Sie einen genaueren Blick auf das sql-docs-Repository werfen.

Außerdem haben Sie die Möglichkeit, Artikel zu suchen, Änderungen einzureichen und die SQL Server-Community zu unterstützen.

Vielen Dank!