Freigeben über

Beitragen von Qualitätsverbesserungen

Sie müssen kein Fachexperte oder Dokumentationsexperte sein, um mitzuwirken. Wenn Sie eine Möglichkeit zur Verbesserung der Dokumentation sehen, übermitteln Sie eine Pull-Anforderung mit Ihrer vorgeschlagenen Verbesserung. In diesem Leitfaden werden mehrere einfache Methoden beschrieben, mit denen jeder eine Verbesserung der Qualität in der Dokumentation beitragen kann.

Wir konzentrieren uns auf diese Qualitätsbereiche:

Formatieren von Codebeispielen

Alle Codebeispiele sollten den Stilrichtlinien für PowerShell-Inhalte entsprechen. Diese Regeln werden hier aus Gründen der Einfachheit in gekürzter Form wiederholt:

  • Alle Codeblöcke sollten in einem dreiseitigen Codezaun (```) enthalten sein.
  • Die Zeilenlänge für Codeblöcke ist auf 90 Zeichen für Cmdlet-Referenzartikel beschränkt.
  • Die Zeilenlänge für Codeblöcke ist auf 76 Zeichen für about_* Artikel beschränkt.
  • Vermeiden Sie die Verwendung von Zeilenfortsetzungszeichen (`) in PowerShell-Codebeispielen.
    • Verwenden Sie Splatting- oder natürliche Zeilenumbruchmöglichkeiten, z. B. nach Pipe (|)-Zeichen, öffnenden geschweiften Klammern (}), runden Klammern (() und eckigen Klammern ([), um die Zeilenlänge zu begrenzen.
  • Fügen Sie nur die PowerShell-Eingabeaufforderung für veranschauliche Beispiele ein, in denen der Code nicht für das Kopieren vorgesehen ist.
  • Verwenden Sie Aliase nicht in Beispielen, es sei denn, Sie dokumentieren speziell den Alias.
  • Vermeiden Sie die Verwendung von Positionsparametern. Verwenden Sie den Parameternamen, auch wenn der Parameter positional ist.

Syntax des Formatierungsbefehls

Alle Prosa sollte den Stilrichtlinien für PowerShell-Inhalte entsprechen. Diese Regeln werden hier zur Vereinfachung wiederholt:

  • Verwenden Sie immer den vollständigen Namen für Cmdlets und Parameter. Vermeiden Sie die Verwendung von Aliasen, es sei denn, Sie zeigen den Alias ausdrücklich an.
  • Eigenschaft, Parameter, Objekt, Typnamen, Klassennamen, Klassenmethoden sollten fett formatiert sein.
    • Eigenschafts- und Parameterwerte sollten in sogenannten Backticks (`) eingeschlossen werden.
    • Wenn Sie auf Typen verweisen, die die Klammerformatvorlage verwenden, verwenden Sie Backticks. Beispiel: [System.Io.FileInfo]
  • PowerShell-Modulnamen sollten fett formatiert sein.
  • PowerShell-Schlüsselwörter und -Operatoren sollten alle Kleinbuchstaben sein.
  • Verwenden Sie die Pascal-Großschreibung für Cmdlet-Namen und -Parameter.
  • Wenn Sie auf einen Parameter anhand des Namens verweisen, sollte der Name fett formatiert sein.
  • Verwenden Sie den Parameternamen mit dem Bindestrich, wenn Sie die Syntax veranschaulichen. Umschließen Sie den Parameter in Backticks.
  • Wenn Sie die Beispielverwendung eines externen Befehls anzeigen, sollte das Beispiel in Backticks umschlossen werden. Schließen Sie immer die Dateierweiterung des externen Befehls ein.

Zur Aufrechterhaltung und Lesbarkeit der Markdownquelle für unsere Dokumentation konvertieren wir unsere konzeptionelle Dokumentation, um Linkverweise anstelle von Inlinelinks zu verwenden.

Verwenden Sie zum Beispiel anstelle von:

The [Packages tab](https://www.powershellgallery.com/packages) displays all available
packages in the PowerShell Gallery.

Es sollte folgendes sein:

The [Packages tab][01] displays all available packages in the PowerShell Gallery.

Hinweis

Wenn Sie einen Inlinelink ersetzen, passen Sie das Layout so an, dass der Inhalt bei 100 Zeichen umbricht. Sie können die VS Code-Erweiterung reflow-markdown verwenden, um den Absatz schnell umzubrechen.

Fügen Sie unten in der Datei einen Markdownkommentar vor der Definition der Links hinzu.

<!-- Link references -->
[01]: https://www.powershellgallery.com/packages

Stellen Sie Folgendes sicher:

  1. Jeder Link verweist auf die richtige Position.
  2. Duplizieren Sie keine Verknüpfungsverweisdefinitionen. Wenn bereits eine Linkverweisdefinition für eine URL vorhanden ist, verwenden Sie den vorhandenen Verweis wieder, anstatt eine neue zu erstellen.
  3. Die Verknüpfungsverweisdefinitionen befinden sich am Ende der Datei nach dem Markdownkommentar und befinden sich in der numerischen Reihenfolge.

Markdown-Linting

Für jeden Artikel in einem der teilnehmenden Repositorys zeigt das Öffnen des Artikels in VS Code Lintingwarnungen an. Adressieren Sie eine dieser Warnungen, die Sie finden, außer:

Stellen Sie sicher, dass die Zeilenlängen korrekt sind, und verwenden Sie die Erweiterung "Reflow Markdown", um lange Zeilen zu korrigieren.

Rechtschreibung

Trotz unserer besten Bemühungen schleichen sich Tippfehler und Rechtschreibfehler in die Dokumentation ein. Diese Fehler machen die Dokumentation schwieriger zu verfolgen und zu lokalisieren. Wenn Sie diese Fehler beheben, wird die Dokumentation besser lesbar, insbesondere für Nicht-Englisch-Sprecher, die auf genaue Übersetzungen angewiesen sind.

  • Last updated on