Dela via

Hjälp med att skriva för PowerShell-cmdlets

  • Artikel

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

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

Skriva riktlinjer för cmdlet-hjälp

Skriv bra

Ingenting ersätter ett välskrivet ämne. Om du inte är professionell författare kan du hitta en författare eller redigerare som hjälper 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.

Skriv helt enkelt

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

Skriva konsekvent

Hjälp för relaterade cmdletar bör vara liknande (till exempel Get-Content och Set-Content). Använd standardbeskrivningarna för standardparametrar, till exempel Force och InputObject. (Kopiera dem från hjälpen för kärn-cmdletarna.) Använd standardvillkor. Använd till exempel "parameter", inte "argument" och använd "cmdlet" inte "command" eller "command-let".

Starta synopsisen med ett verb

Synopsis-fä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 den här cmdleten uppfyller deras krav. Använd enkla verb som "get", "create" och "change". Undvik "set", som kan vara vaga och snygga ord som "ändra".

Fokusera på objekt

De flesta "get"-cmdletar visar något, men deras primära funktion är att hämta ett objekt. I hjälpen fokuserar du på objektet 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 åt dem på olika sätt.

Skriva detaljerade beskrivningar

Lista kort 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änd konventionell syntax

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

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

Platshållarna för parametervärden (i syntax- och parameterbeskrivningarna) visar .NET Framework-typerna för de objekt som parametern kommer att acceptera. PowerShell-teamet utvecklade den här konventionen för att lära användarna om .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 du hur du använder cmdleten i en pipeline.

Använd 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ändare att undvika vanliga fel. Undvik URL:er när de ändras. Ange i stället användarvillkor att söka efter.

Testa din hjälp

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

Se även