Help voor PowerShell-cmdlets schrijven

Artikel
09/25/2021
3 minuten om te lezen

PowerShell-cmdlets kunnen nuttig zijn, maar tenzij in uw Help-onderwerpen duidelijk wordt uitgelegd wat de cmdlet doet en hoe u deze gebruikt, kan de cmdlet mogelijk niet worden gebruikt of, nog erger, het kan gebruikers gefrustreerd raken. De Help-bestandsindeling van de op XML gebaseerde cmdlet verbetert de consistentie, maar veel hulp vereist veel meer.

Als u nog nooit help voor cmdlet hebt geschreven, bekijkt u de volgende richtlijnen. Het XML-schema dat is vereist voor het schrijven van het Help-onderwerp voor de cmdlet wordt in de volgende sectie beschreven. Begin met het maken van het Help-bestand van de cmdlet. Dit onderwerp bevat een beschrijving van de XML-knooppunten op het hoogste niveau.

Richtlijnen schrijven voor cmdlet Help

Goed schrijven

Niets vervangt een goed geschreven onderwerp. Als u geen professionele schrijver bent, zoek dan een schrijver of editor om u te helpen. Een ander alternatief is om uw Help-tekst te kopiëren naar Microsoft Word en de grammatica- en spellingcontroles te gebruiken om uw werk te verbeteren.

Gewoon schrijven

Gebruik eenvoudige woorden en woordgroepen. Vermijd jargon. Houd er rekening mee dat veel lezers alleen zijn uitgerust met een woordenlijst met vreemde talen en uw Help-onderwerp.

Consistent schrijven

De help voor gerelateerde cmdlets moet vergelijkbaar zijn (bijvoorbeeld get-x en set-x). Gebruik de standaardbeschrijvingen voor standaardparameters, zoals Force en InputObject. (Kopieer ze uit de Help voor de kern-cmdlets.) Gebruik standaardvoorwaarden. Gebruik bijvoorbeeld 'parameter', niet 'argument' en gebruik 'cmdlet' niet 'command' of 'command-let'.

Het synopsis starten met een werkwoord

Het veld Synopsis informeert de gebruiker wat de cmdlet doet, niet wat het is of hoe deze werkt. Werkwoorden maken een taakin instructie die gebruikers informeert als deze cmdlet aan hun vereisten voldoet. Gebruik eenvoudige woorden als 'get', 'create' en 'change'. Vermijd 'set', wat leuke en mooie woorden kan zijn, zoals 'wijzigen'.

Focus op objecten

De meeste get-cmdlets geven iets weer, maar hun primaire functie is om een -object op te halen. Richt u in de Help op het object, zodat gebruikers begrijpen dat de standaardweergave een van de vele is en dat ze de methoden en eigenschappen van het object dat u voor hen hebt opgehaald op verschillende manieren kunnen gebruiken.

Gedetailleerde beschrijvingen schrijven

Vermeld kort alles wat de cmdlet kan doen in de gedetailleerde beschrijving. Als de hoofdfunctie is om één eigenschap te wijzigen, maar de cmdlet alle eigenschappen kan wijzigen, vermeldt u deze in de gedetailleerde beschrijving.

Conventionele syntaxis gebruiken

Gebruik de standaard Backus-Naur-indeling die gebruikelijk is voor Windows en UNIX Help-opdrachtregel.

Gebruik Microsoft .NET voor parameterwaarden

De tijdelijke aanduidingen voor parameterwaarden (in de syntaxis en parameterbeschrijvingen) geven de .NET Framework van de objecten weer die de parameter accepteert. Het PowerShell-team heeft deze conventie ontwikkeld om gebruikers te helpen bij het leren van .NET Framework.

Volledige parameterbeschrijvingen schrijven

Parameterbeschrijvingen moeten gebruikers informeren over twee dingen: wat de parameter doet (het effect ervan) en wat ze moeten typen voor de parameterwaarden.

Praktische voorbeelden schrijven

De voorbeelden moeten laten zien hoe u alle parameters gebruikt, maar het belangrijkste is om te laten zien hoe u de cmdlet gebruikt in echte taken. Begin met een eenvoudig voorbeeld en schrijf steeds complexere voorbeelden. Laat in het laatste voorbeeld zien hoe u de cmdlet in een pijplijn gebruikt.

Het veld Notities gebruiken

Gebruik het veld Notities om concepten uit te leggen die gebruikers nodig hebben om de cmdlet te begrijpen. U kunt ook notities gebruiken om gebruikers te helpen veelvoorkomende fouten te voorkomen. Vermijd URL's wanneer deze veranderen. Geef in plaats daarvan gebruikerstermen op waar naar moet worden gezocht.

Uw Help testen

Test de Help net zoals u uw code test. Zorg ervoor dat vrienden en collega's uw Help-inhoud lezen en feedback geven. U kunt ook feedback vragen van nieuwsgroepen.