Mitwirken an der Iis-Dokumentation (Internet Information Services)

Dieses Dokument behandelt den Prozess für den Beitrag zu den Artikeln und Codebeispielen, die auf der IIS-Dokumentationswebsite gehostet werden. Beiträge können typografische Korrekturen oder so komplex wie neue Artikel sein.

So wird's gemacht: Erstellen einer einfachen Korrektur oder eines Vorschlags

Artikel werden im Repository als Markdown-Dateien gespeichert. Kleine Änderungen am Inhalt einer Markdown-Datei können im Browser vorgenommen werden, indem Sie den Link "Bearbeiten" in der oberen rechten Ecke des Browserfensters auswählen. (In schmalen Browserfenstern müssen Sie die Optionsleiste erweitern, um den Link " Bearbeiten " anzuzeigen.) Folgen Sie den Anweisungen, um eine Pullanforderung (PR) zu erstellen. Wir werden die PR überprüfen und annehmen oder Änderungen vorschlagen.

So erstellen Sie eine komplexere Übermittlung

Sie benötigen ein grundlegendes Verständnis von Git und GitHub.com.

  • Öffnen Sie ein Problem , das beschreibt, was Sie tun möchten, z. B. einen vorhandenen Artikel ändern oder einen neuen erstellen. Warten Sie auf die Genehmigung des Teams, bevor Sie viel Zeit investieren.
  • Forken Sie das iis-docs-Repository und erstellen Sie einen Branch für Ihre Änderungen.
  • Übermitteln Sie eine Pull-Request (PR) mit Ihren Änderungen an den Master-Branch.
  • Wenn ihr PR das Label "cla-required" zugewiesen hat, füllen Sie den Mitwirkungsvertrag (CLA) aus.
  • Antworten Sie auf PR-Feedback.

Ein Beispiel, bei dem dieser Prozess zur Veröffentlichung eines neuen Artikels geführt hat, finden Sie unter Problem 67 und Pullanforderung 798 im .NET-Repository. Der neue Artikel dokumentiert Ihren Code.

Markdown-Syntax

Artikel werden in DocFx-aromatisiertem Markdown geschrieben, was eine Obermenge von GitHub-aromatisierten Markdown (GFM) ist. Beispiele für die DFM-Syntax für häufig in der Dokumentation verwendete UI-Features finden Sie in der .NET-Repositorystilanleitung unter Metadaten und Markdown-Vorlage .

Konventionen der Ordnerstruktur

Für jede Markdown-Datei gibt es möglicherweise einen Ordner für Bilder und einen Ordner für Beispielcode. Wenn der Artikel beispielsweise "/extensions/advanced-logging-module/advanced-logging-for-iis-client-logging.md" lautet, befinden sich die Bilder in Erweiterungen/advanced-logging-module/advanced-logging-for-iis-client-loggin/_static und die Beispielanwendungsprojektdateien befinden sich in Erweiterungen/advanced-logging-module/advanced-logging-for-iis-client-loggin/samples. Ein Bild in der Datei "/advanced-logging-for-iis-client-logging.md " wird durch den folgenden Markdown gerendert.

![description of image for alt attribute](advanced-logging-for-iis-client-logging/_static/imagename.png)

Alle Bilder sollten Alt-Text enthalten.

Markdown-Dateinamen und Bilddateinamen sollten alle Kleinbuchstaben sein.

Codeausschnitte

Artikel enthalten häufig Codeausschnitte, um Punkte zu veranschaulichen. Mit DFM können Sie Code in die Markdown-Datei kopieren oder auf eine separate Codedatei verweisen. Wir verwenden nach Möglichkeit separate Codedateien, um die Wahrscheinlichkeit von Fehlern im Code zu minimieren. Die Codedateien sollten im Repository mithilfe der oben beschriebenen Ordnerstruktur für Beispielprojekte gespeichert werden.

Nachfolgend finden Sie einige Beispiele für dfM-Codeausschnittsyntax , die in einer configuration.md Datei verwendet werden würde.

So rendern Sie eine gesamte Codedatei als Codeausschnitt:

[!code-csharp[Main](configuration/sample/Program.cs)]

So rendern Sie einen Teil einer Datei als Codeausschnitt mithilfe von Zeilennummern:

[!code-csharp[Main](configuration/sample/Program.cs?range=1-10,20,30,40-50]
[!code-html[Main](configuration/sample/Views/Home/Index.cshtml?range=1-10,20,30,40-50]

Bei C#-Codeausschnitten können Sie auf einen C#-Bereich verweisen. Verwenden Sie nach Möglichkeit Regionen anstelle von Zeilennummern, da Zeilennummern in einer Codedatei dazu neigen, sich zu ändern und mit den Zeilennummernverweisen in Markdown nicht mehr synchron zu sein. C#-Bereiche können geschachtelt werden, und wenn Sie auf den äußeren Bereich verweisen, werden die inneren #region und #endregion direktiven nicht in einem Codeausschnitt gerendert.

So rendern Sie einen C#-Bereich namens "snippet_Example":

[!code-csharp[Main](configuration/sample/Program.cs?name=snippet_Example)]

So markieren Sie ausgewählte Linien in einem gerenderten Codeausschnitt (wird in der Regel als gelbe Hintergrundfarbe gerendert):

[!code-csharp[Main](configuration/sample/Program.cs?name=snippet_Example&highlight=1-3,10,20-25)]
[!code-csharp[Main](configuration/sample/Program.cs?range=10-20&highlight=1-3]
[!code-html[Main](configuration/sample/Views/Home/Index.cshtml?range=10-20&highlight=1-3]
[!code-javascript[Main](configuration/sample/Project.json?range=10-20&highlight=1-3]

Testen Ihrer Änderungen mit DocFX

Testen Sie Ihre Änderungen mit dem DocFX-Befehlszeilentool, das eine lokal gehostete Version der Website erstellt. DocFX rendert keine Formatvorlagen und Websiteerweiterungen, die für learn.microsoft.com erstellt wurden.

DocFX erfordert .NET Framework unter Windows oder Mono für Linux oder macOS.

Windows-Anweisungen

  • Laden Sie docfx.zip aus DocFX-Versionen herunter und entpacken Sie sie.

  • Fügen Sie DocFX zu Ihrem PATH hinzu.

  • Navigieren Sie in einem Befehlszeilenfenster zu dem entsprechenden Ordner, der die docfx.json Datei (iis-docs/iis) enthält, und führen Sie den folgenden Befehl aus:

    docfx -t default --serve

  • Navigieren Sie in einem Browser zu http://localhost:8080.

Mono-Anweisungen

  • Installieren Sie Mono über Homebrew - brew install mono.

  • Laden Sie die neueste Version von DocFX herunter.

  • Extrahieren in \bin\docfx.

  • Erstellen sie einen Alias für docfx:

    function docfx {
  mono $HOME/bin/docfx/docfx.exe
}

function docfx-serve {
  mono $HOME/bin/docfx/docfx.exe serve _site
}

  • Führen Sie docfx im iis-docs\iisVerzeichnis aus, um die Website zu erstellen, und docfx-serve zum Anzeigen der Website unter http://localhost:8080.

Sprache und Tonfall

Unser Ziel ist es, Dokumentationen zu schreiben, die vom größtmöglichen Publikum leicht verständlich sind. Zu diesem Zweck haben wir Richtlinien für schreibstile festgelegt, die wir unsere Mitwirkenden bitten, zu folgen. Weitere Informationen finden Sie in den Sprach- und Tonrichtlinien im .NET-Repository.

Weiterleitungen

Wenn Sie einen Artikel löschen, den Dateinamen ändern oder in einen anderen Ordner verschieben, erstellen Sie eine Umleitung, sodass Personen, die ein Lesezeichen für den Artikel erstellt haben, keine 404s erhalten. Fügen Sie der Hauptumleitungsdatei Umleitungen hinzu.

  • Last updated on