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.

Das SQL-Inhaltsteam prüft alle öffentlichen Beiträge auf technische Richtigkeit und Konsistenz.

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 das Bleistift-Symbol aus.
  2. Wählen Sie auf der nächsten Seite oben rechts das Symbol Stift aus. Wenn dieses Symbol nicht angezeigt wird, müssen Sie sich gegebenenfalls zuerst bei Ihrem GitHub-Konto anmelden.
  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. Gehen Sie nach dem Vornehmen Ihrer Änderungen unter Änderungen übernehmen folgendermaßen vor:
    1. Geben Sie im ersten Textfeld eine kurze Beschreibung der Änderung ein, die Sie vornehmen.
    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:

Screenshot of Edit SQL Docs.

Lokales Bearbeiten von Inhalten mit Tools

Eine weitere Bearbeitungsoption besteht darin, das sql-docs- oder azure-docs-Repository zu forken und 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 an technischer Microsoft-Dokumentation 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 (CLA) 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.

Screenshot of Content contribution recognition.

Übersicht über SQL-docs

Dieser Abschnitt enthält weitere Hinweise zur Arbeit im sql-docs-Repository.

Wichtig

Die Informationen in diesem Abschnitt beziehen sich ausschließlich auf sql-docs. Wenn Sie einen SQL-Artikel in 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 andere 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 eine applies-to-Includedatei. Damit wird angegeben, auf welche Bereiche oder Versionen von SQL Server sich der Artikel bezieht.

Im folgenden Markdown-Beispiel wird die applies-to-version/sql-asdb-asa-pdw.md-Includedatei 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:

Screenshot of 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 rendert.
  • Beachten Sie die Namenskonvention. Wenn der Name mehrmals den das Zeichen x in der Zeichenkette enthält, handelt es sich vermutlich um Platzhalter, die darauf hinweisen, 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 asdw ausgeschrieben ist. Die anderen Felder enthalten hingegen nur x.
  • Einige Includes enthalten eine Versionsnummer, wie z. B. tsql-appliesto-ss2017-xxxx-xxxx-xxx-md.md. 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.

Zugehöriger Inhalt

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.

Wir bedanken uns für Ihre Hilfe.