Freigeben über

Schreiben einer Hilfe für PowerShell-Cmdlets

  • Artikel

PowerShell-Cmdlets können nützlich sein, aber es sei denn, Ihre Hilfethemen erläutern eindeutig, was das Cmdlet tut und wie es verwendet werden kann, kann das Cmdlet nicht verwendet werden oder noch schlimmer, es könnte Benutzer frustrieren. Das XML-basierte Cmdlet-Hilfedateiformat verbessert die Konsistenz, aber große Hilfe erfordert viel mehr.

Wenn Sie noch nie die Cmdlet-Hilfe geschrieben haben, lesen Sie die folgenden Richtlinien. Das zum Erstellen des Hilfethemas für cmdlets erforderliche XML-Schema wird im folgenden Abschnitt beschrieben. Beginnen Sie mit Erstellen der Cmdlet-Hilfedatei. Dieses Thema enthält eine Beschreibung der XML-Knoten der obersten Ebene.

Schreiben von Richtlinien für cmdlet-Hilfe

Gut schreiben

Nichts ersetzt ein gut geschriebenes Thema. Wenn Sie kein professioneller Autor sind, suchen Sie einen Autor oder Editor, um Ihnen zu helfen. Eine weitere Alternative besteht darin, Ihren Hilfetext in Microsoft Word zu kopieren und die Grammatik- und Rechtschreibprüfung zu verwenden, um Ihre Arbeit zu verbessern.

Einfach schreiben

Verwenden Sie einfache Wörter und Ausdrücke. Vermeiden Sie Jargon. Beachten Sie, dass viele Leser nur mit einem Fremdsprachenwörterbuch und Ihrem Hilfethema ausgestattet sind.

Konsistentes Schreiben

Die Hilfe zu verwandten Cmdlets sollte ähnlich sein (z. B. Get-Content und Set-Content). Verwenden Sie die Standardbeschreibungen für Standardparameter wie Force und InputObject-. (Kopieren Sie sie aus der Hilfe für die wichtigsten Cmdlets.) Verwenden Sie Standardbegriffe. Verwenden Sie z. B. "Parameter", nicht "Argument", und verwenden Sie "Cmdlet" nicht "Befehl" oder "Befehls let".

Starten der Synopsis mit einem Verb

Das Feld "Synopsis" informiert den Benutzer darüber, was das Cmdlet tut, nicht was es ist oder wie es funktioniert. Verben erstellen eine aufgabenbasierte Anweisung, die Benutzer darüber informiert, ob dieses Cmdlet ihre Anforderungen erfüllt. Verwenden Sie einfache Verben wie "get", "create" und "change". Vermeiden Sie "set", was vage und ausgefallene Wörter wie "modify" sein kann.

Fokus auf Objekte

Die meisten "get"-Cmdlets zeigen etwas an, aber ihre primäre Funktion besteht darin, ein Objekt abzurufen. Konzentrieren Sie sich in Ihrer Hilfe auf das Objekt, damit Benutzer verstehen, dass die Standardanzeige eine von vielen ist und dass sie die Methoden und Eigenschaften des Objekts verwenden können, das Sie für sie auf unterschiedliche Weise abgerufen haben.

Detaillierte Beschreibungen schreiben

Listet kurz alles auf, was das Cmdlet in der detaillierten Beschreibung ausführen kann. Wenn die Hauptfunktion eine Eigenschaft ändern soll, aber das Cmdlet alle Eigenschaften ändern kann, listen Sie dies in der detaillierten Beschreibung auf.

Verwenden der herkömmlichen Syntax

Verwenden Sie das standardformat Backus-Naur, das für die Befehlszeilenhilfe für Windows und Unix üblich ist.

Verwenden von Microsoft .NET-Typen für Parameterwerte

Die Platzhalter für Parameterwerte (in den Syntax- und Parameterbeschreibungen) zeigen die .NET Framework-Typen der Objekte an, die der Parameter akzeptiert. Das PowerShell-Team hat diese Konvention entwickelt, um Benutzern das .NET Framework zu vermitteln.

Schreiben vollständiger Parameterbeschreibungen

Parameterbeschreibungen müssen Benutzer über zwei Dinge informieren: was der Parameter bewirkt (seine Wirkung) und was sie für die Parameterwerte eingeben müssen.

Schreiben von praktischen Beispielen

In den Beispielen sollte gezeigt werden, wie Sie alle Parameter verwenden, aber am wichtigsten ist die Verwendung des Cmdlets in realen Aufgaben. Beginnen Sie mit einem einfachen Beispiel, und schreiben Sie immer komplexere Beispiele. Im letzten Beispiel wird gezeigt, wie das Cmdlet in einer Pipeline verwendet wird.

Verwenden des Felds "Notizen"

Verwenden Sie das Feld "Notizen", um Konzepte zu erläutern, die Benutzer zum Verständnis des Cmdlets benötigen. Sie können auch Notizen verwenden, um Benutzern zu helfen, häufige Fehler zu vermeiden. Vermeiden Sie URLs, während sie sich ändern. Stellen Sie stattdessen Benutzerbegriffe bereit, nach der gesucht werden soll.

Testen Ihrer Hilfe

Testen Sie die Hilfe genau so, wie Sie Ihren Code testen. Lassen Sie Freunde und Kollegen Ihre Hilfeinhalte lesen und Feedback geben. Sie können auch Feedback von Newsgroups anfordern.

Siehe auch