Feedback

De cmdlet-naam en het cmdlet-overzicht toevoegen aan een Help-onderwerp voor cmdlets

  • Artikel
  • 2 minuten om te lezen

In deze sectie wordt beschreven hoe u inhoud toevoegt die wordt weergegeven in de secties NAAM en SYNOPSIS van de help voor de cmdlet. In het Help-bestand wordt deze inhoud toegevoegd aan het knooppunt Opdracht voor elke cmdlet.

Notitie

Voor een volledige weergave van een Help-bestand opent u een van de dll-Help.xml bestanden in de PowerShell-installatiemap. Het bestand bevat Microsoft.PowerShell.Commands.Management.dll-Help.xml bijvoorbeeld inhoud voor verschillende PowerShell-cmdlets.

De cmdlet-naam en een samenvatting toevoegen

  • De Help-cmdlet kan twee beschrijvingen voor de cmdlet weergeven. De eerste beschrijving is een korte beschrijving die het synopsis wordt genoemd. De tweede beschrijving is een meer gedetailleerde beschrijving die wordt besproken in Adding the Detailed Description to a Cmdlet Help Topic (Gedetailleerde beschrijving toevoegen aan een Help-onderwerp voor cmdlet). Beide beschrijvingen moeten als één alinea worden geschreven.

  • Herhaal de naam van de cmdlet niet in het overzicht. De gebruiker informeren dat de Get-Server cmdlet een server krijgt, is kort, maar niet informatief. Gebruik in plaats daarvan synoniemen en voeg details toe aan de beschrijving.

    Voorbeeld: 'Haalt een object op dat een lokale of externe computer vertegenwoordigt.'

  • Gebruik eenvoudige werkwoorden zoals 'get', 'create' en 'change' in het overzicht. Vermijd het gebruik van 'set', omdat het nogal aan de hand is, en mooie woorden zoals 'wijzigen'.

    Voorbeeld: 'Haalt informatie op over de Authenticode-handtekening in een bestand.'

  • Schrijf in actieve spraak. Bijvoorbeeld 'Use the TimeSpan object...' (Het TimeSpan-object gebruiken...) is veel duidelijker dan 'het TimeSpan-object kan worden gebruikt...'

  • Vermijd het woord 'display' bij het beschrijven van cmdlets die objecten krijgen. Hoewel Windows PowerShell cmdlet-gegevens we weergeven, is het belangrijk om gebruikers kennis te laten maken met het concept dat de cmdlet retourneert .NET Framework objecten waarvan de gegevens mogelijk niet worden weergegeven. Als u de weergave benadrukt, realiseert de gebruiker zich mogelijk niet dat de cmdlet mogelijk veel andere nuttige eigenschappen en methoden heeft geretourneerd die niet worden weergegeven.

Zie ook

Windows PowerShell SDK