Skriva hjälp för PowerShell-cmdletar

Artikel
09/25/2021
2 minuter för att läsa

PowerShell-cmdlets kan vara användbara, men om inte hjälpavsnitten tydligt förklarar vad cmdleten gör och hur den används, kanske cmdleten inte används eller, ännu värre, det kan frustrera användarna. Det XML-baserade cmdlet-hjälpfilformatet förbättrar konsekvensen, men bra hjälp kräver mycket mer.

Om du aldrig har skrivit cmdlet-hjälpen kan du läsa följande riktlinjer. Det XML-schema som krävs för att skapa cmdlet-hjälpavsnittet beskrivs i följande avsnitt. Börja med att skapa cmdlet-hjälpfilen. Avsnittet innehåller en beskrivning av XML-noderna på den översta nivån.

Skriva riktlinjer för cmdlet-hjälp

Skrivskydd

Inget ersätter ett välskrivet ämne. Om du inte är en professionell skrivare kan du hitta en skrivare eller ett redigeringsprogram som kan hjälpa dig. Ett annat alternativ är att kopiera hjälptexten till Microsoft Word och använda grammatik- och stavningskontrollerna för att förbättra ditt arbete.

Skriva helt enkelt

Använd enkla ord och fraser. Undvik jargong. Tänk på att många läsare bara är utrustade med en ordlista på ett främmande språk och ditt hjälpavsnitt.

Skriva konsekvent

Hjälpen för relaterade cmdlets bör vara liknande (till exempel get-x och set-x). Använd standardbeskrivningarna för standardparametrar som Force och InputObject. (Kopiera dem från Hjälpen för kärn-cmdlets.) Använd standardvillkor. Använd till exempel "parameter", inte "argument" och använd "cmdlet" inte "kommando" eller "command-let".

Starta sammanfattningen med ett verb

Sammanfattningsfältet informerar användaren om vad cmdleten gör, inte vad den är eller hur den fungerar. Verb skapar en uppgiftsbaserad instruktion som informerar användarna om denna cmdlet uppfyller deras krav. Använd enkla verb som "get", "create" och "change". Undvik "set", som kan vara vaga och fancy ord som "ändra".

Fokusera på objekt

De flesta "get"-cmdlets visar något, men deras primära funktion är att hämta ett -objekt. Fokusera på objektet i hjälpen så att användarna förstår att standardvisningen är en av många och att de kan använda metoderna och egenskaperna för det objekt som du hämtade för dem på olika sätt.

Skriva detaljerade beskrivningar

Visa en kort lista över allt som cmdleten kan göra i den detaljerade beskrivningen. Om huvudfunktionen är att ändra en egenskap, men cmdleten kan ändra alla egenskaper, anger du detta i den detaljerade beskrivningen.

Använda konventionell syntax

Använd standardformatet Backus-Naur som är vanligt för Windows och UNIX för kommandoradshjälp.

Använda Microsoft .NET-typer för parametervärden

Platshållarna för parametervärden (i syntaxen och parameterbeskrivningarna) visar .NET Framework typer av objekt som parametern accepterar. PowerShell-teamet har utvecklat den här konventionen för att hjälpa användarna att lära sig .NET Framework.

Skriva fullständiga parameterbeskrivningar

Parameterbeskrivningar måste informera användarna om två saker: vad parametern gör (dess effekt) och vad de måste skriva för parametervärdena.

Skriva praktiska exempel

Exemplen bör visa hur du använder alla parametrar, men det viktigaste är att visa hur du använder cmdleten i verkliga uppgifter. Börja med ett enkelt exempel och skriv allt mer komplexa exempel. I det sista exemplet visar vi hur du använder cmdleten i en pipeline.

Använda fältet Anteckningar

Använd fältet Anteckningar för att förklara begrepp som användarna behöver för att förstå cmdleten. Du kan också använda anteckningar för att hjälpa användarna att undvika vanliga fel. Undvik URL:er när de ändras. Ange i stället användarnas villkor att söka efter.

Testa din hjälp

Testa hjälpen precis som du testar koden. Be vänner och kollegor läsa ditt hjälpinnehåll och ge feedback. Du kan också begära feedback från nyhetsgrupper.