Freigeben über

Prüfliste des Editors

Dieser Artikel enthält eine zusammengefasste Liste der Regeln zum Schreiben oder Bearbeiten der PowerShell-Dokumentation. Ausführliche Erläuterungen und Beispiele für diese Regeln finden Sie in den anderen Artikeln im Leitfaden für Mitwirkende.

Metadaten

  • ms.date: muss im Format MM/TT/JJJJ vorliegen.
    • Ändern des Datums, an dem ein signifikantes oder tatsächliches Update vorhanden ist
      • Neuorganisieren des Artikels
      • Beheben von Faktenfehlern
      • Hinzufügen neuer Informationen
    • Ändern Sie das Datum nicht, wenn das Update unbedeutend ist.
      • Korrigieren von Tippfehlern und Formatierungen
  • title: eindeutige Zeichenfolge von 43-59 Zeichen lang (einschließlich Leerzeichen)
    • Websitebezeichner nicht einschließen (automatisch generiert)
    • Verwenden Sie die Satz-Großschreibung – nur das erste Wort und alle Eigennamen werden großgeschrieben.
  • description: 115-145 Zeichen einschließlich Leerzeichen - dieses Abstrakte wird im Suchergebnis angezeigt.

Formatierung

  • Backtick-Syntaxelemente, die innerhalb eines Absatzes inline angezeigt werden
    • Cmdlet-Namen Verb-Noun
    • Variable $counter
    • Syntaktische Beispiele Verb-Noun -Parameter
    • Dateipfade C:\Program Files\PowerShell, /usr/bin/pwsh
    • URLs, die nicht im Dokument geklickt werden sollen
    • Eigenschafts- oder Parameterwerte
  • Verwenden von Fett für Eigenschaftennamen, Parameternamen, Klassennamen, Modulnamen, Entitätsnamen, Objekt- oder Typnamen
    • Fett wird für semantisches Markup verwendet, nicht für Hervorhebung
    • Fett - Sternchen benutzen **
  • Kursiv – Unterstrich verwenden _
    • Wird nur für Hervorhebung verwendet, nicht für semantisches Markup
  • Zeilenumbrüche bei 100 Spalten (oder bei 80 für about_Topics)
  • Keine harten Tabulatoren – nur Leerzeichen verwenden
  • Keine Leerzeichen am Zeilenende
  • PowerShell-Schlüsselwörter und -Operatoren sollten alle Kleinbuchstaben sein
  • Verwenden Sie die korrekte Pascal-Schreibweise für Cmdlet-Namen und -Parameter

Überschriften

  • Beginnen Sie mit H1 zuerst - nur ein H1 pro Artikel
  • Nur ATX-Header verwenden
  • Verwenden Sie Satzschreibung für alle Kopfzeilen
  • Überspringen Sie keine Ebenen - kein H3 ohne H2
  • Beschränken der Kopfzeilentiefe auf H3 oder H4
  • Hinzufügen leerer Zeilen vor und nachher
  • Keine Kopfzeilen hinzufügen oder entfernen – PlatyPS erzwingt bestimmte Header in seinem Schema

Codeblöcke

  • Hinzufügen leerer Zeilen vor und nachher
  • Verwenden von markierten Codezäunen – PowerShell, Output oder einer anderen geeigneten Sprach-ID
  • Verwenden Sie einen unmarkierten Codebereich für Syntaxblöcke
  • Einfügen der Ausgabe in separaten Codeblock mit Ausnahme grundlegender Beispiele, in denen der Leser die Schaltfläche "Kopieren " nicht verwenden soll
  • Siehe Liste der unterstützten Sprachen

Listet

  • Richtig einrücken
  • Hinzufügen leerer Zeilen vor dem ersten Element und nach dem letzten Element
  • Verwenden Sie Bindestriche (-) für Aufzählungszeichen, die kein Sternchen (*) sind, um Verwirrung mit Hervorhebung zu reduzieren.
  • Wird für alle Elemente in einer nummerierten Liste verwendet 1.

Terminologie

Cmdlet-Referenzbeispiele

  • Muss mindestens ein Beispiel in der Cmdlet-Referenz aufweisen

  • Beispiele sollten nur so viel Code enthalten, um die Verwendung zu veranschaulichen.

  • PowerShell-Syntax

    • Vollständige Namen von Cmdlets und Parametern verwenden – keine Aliase
    • Verwenden Sie Splatting für Parameter, wenn die Befehlszeile zu lang wird
    • Vermeiden Sie die Verwendung von Zeilenfortsetzungs-Backticks – nur bei Notwendigkeit verwenden.

  • Entfernen oder vereinfachen Sie die PowerShell-Eingabeaufforderung (PS>), es sei denn, sie wird für das Beispiel benötigt.

  • Cmdlet-Referenzbeispiel muss dem folgenden PlatyPS-Schema folgen

    ### Example 1 - Descriptive title

Zero or more short descriptive paragraphs explaining the context of the example followed by one or
more code blocks. Recommend at least one and no more than two.

```powershell
... one or more PowerShell code statements ...
```

```Output
Example output of the code above.
```

Zero or more optional follow up paragraphs that explain the details of the code and output.

  • Keine Absätze zwischen den Codeblöcken einfügen. Alle beschreibenden Inhalte müssen vor oder nach den Codeblöcken erfolgen.

Verknüpfen mit anderen Dokumenten

  • Beim Verknüpfen außerhalb des Docsets oder zwischen Cmdlet-Referenz und konzeptuellem Konzept
    • Verwenden Sie seitenrelative URLs beim Verknüpfen mit Microsoft Learn (entfernen Sie https://learn.microsoft.com/en-us)
    • Vermeiden Sie Lokalisierungen in URLs auf Websites von Microsoft (entfernen Sie /en-us aus der URL)
    • Alle URLs für externe Websites sollten HTTPS verwenden, es sei denn, dies ist für die Zielwebsite nicht gültig.
  • Beim Verknüpfen innerhalb des Dokumentensets
    • Verwenden Sie den relativen Dateipfad (../folder/file.md)
  • Alle Pfade verwenden Schrägstriche (/)
  • Bildlinks sollten über eindeutigen Alternativtext verfügen
  • Last updated on