Delen via

Help voor PowerShell-cmdlets schrijven

  • Artikel

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

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

Richtlijnen schrijven voor Help voor cmdlets

Schrijf goed

Niets vervangt een goed geschreven onderwerp. Als u geen professionele schrijver bent, zoekt u een schrijver of editor om u te helpen. Een ander alternatief is om uw Help-tekst naar Microsoft Word te kopiëren 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 voor vreemde talen en uw Help-onderwerp.

Consistent schrijven

Help voor gerelateerde cmdlets moet vergelijkbaar zijn (bijvoorbeeld Get-Content en Set-Content). Gebruik de standaardbeschrijvingen voor standaardparameters, zoals Forceer en InputObject. (Kopieer deze vanuit Help voor de kern-cmdlets.) Gebruik standaardtermen. Gebruik bijvoorbeeld 'parameter', niet 'argument' en gebruik 'cmdlet' niet 'command' of 'command-let'.

De synopsis starten met een werkwoord

Het synopsisveld informeert de gebruiker wat de cmdlet doet, niet wat het is of hoe het werkt. Werkwoorden maken een op taken gebaseerde instructie die gebruikers informeert als deze cmdlet aan hun vereisten voldoet. Gebruik eenvoudige werkwoorden zoals 'get', 'create' en 'change'. Vermijd 'set', wat vaag en uitgebreid 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 uw Help op het object, zodat gebruikers begrijpen dat de standaardweergave een van de vele is en dat ze de methoden en eigenschappen kunnen gebruiken van het object dat u voor hen op verschillende manieren hebt opgehaald.

Gedetailleerde beschrijvingen schrijven

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

Conventionele syntaxis gebruiken

Gebruik de standaardindeling Backus-Naur die gebruikelijk is voor Windows- en Unix-opdrachtregelhulp.

Microsoft .NET-typen gebruiken voor parameterwaarden

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

Volledige parameterbeschrijvingen schrijven

Parameterbeschrijvingen moeten gebruikers op de hoogte stellen van 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 complexer voorbeelden. In het laatste voorbeeld ziet u 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 inzicht te hebben in de cmdlet. U kunt ook notities gebruiken om gebruikers te helpen veelvoorkomende fouten te voorkomen. Vermijd URL's wanneer ze veranderen. Geef in plaats daarvan gebruikerstermen op om naar te zoeken.

Uw Help testen

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

Zie ook