Condividi tramite

Scrittura della Guida per i cmdlet di PowerShell

  • Articolo

I cmdlet di PowerShell possono essere utili, ma a meno che gli argomenti della Guida non spieghino chiaramente cosa fa il cmdlet e come usarlo, il cmdlet potrebbe non essere usato o, ancora peggio, potrebbe frustrare gli utenti. Il formato di file della Guida del cmdlet basato su XML migliora la coerenza, ma è molto più utile.

Se la Guida dei cmdlet non è mai stata scritta, esaminare le linee guida seguenti. Lo schema XML necessario per creare l'argomento della Guida del cmdlet è descritto nella sezione seguente. Iniziare con Creazione del file della Guida dei cmdlet. Questo argomento include una descrizione dei nodi XML di primo livello.

Scrittura di linee guida per i cmdlet

Scrivi bene

Niente sostituisce un argomento ben scritto. Se non sei uno scrittore professionista, trova uno scrittore o un editor per aiutarti. Un'altra alternativa consiste nel copiare il testo della Guida in Microsoft Word e usare i controlli grammaticali e ortografici per migliorare il lavoro.

Scrivere semplicemente

Usare parole e frasi semplici. Evitare il gergo. Si consideri che molti lettori sono dotati solo di un dizionario di lingua straniera e l'argomento della Guida.

Scrivere in modo coerente

La Guida per i cmdlet correlati deve essere simile, ad esempio Get-Content e Set-Content. Usare le descrizioni standard per i parametri standard, ad esempio Force e InputObject. Copiarli dalla Guida per i cmdlet di base. Usare le condizioni standard. Ad esempio, usare "parameter", non "argument" e usare "cmdlet" non "command" o "command-let".

Avviare il riepilogo con un verbo

Il campo synopsis informa l'utente che cosa fa il cmdlet, non quello che funziona o come funziona. I verbi creano un'istruzione basata su attività che informa gli utenti se questo cmdlet soddisfa i requisiti. Usare verbi semplici come "get", "create" e "change". Evitare "set", che può essere vaga e fantasia parole come "modify".

Concentrarsi sugli oggetti

La maggior parte dei cmdlet "get" visualizza qualcosa, ma la funzione principale consiste nel ottenere un oggetto . Nella Guida concentrarsi sull'oggetto, in modo che gli utenti comprendano che la visualizzazione predefinita è una di molte e che possono usare i metodi e le proprietà dell'oggetto recuperato per loro in modi diversi.

Scrivere descrizioni dettagliate

Elenca brevemente tutto ciò che il cmdlet può eseguire nella descrizione dettagliata. Se la funzione principale consiste nel modificare una proprietà, ma il cmdlet può modificare tutte le proprietà, elencarlo nella descrizione dettagliata.

Usare la sintassi convenzionale

Usare il formato standard Backus-Naur comune per la Guida della riga di comando di Windows e Unix.

Usare i tipi Microsoft .NET per i valori dei parametri

I segnaposto per i valori dei parametri (nella sintassi e nelle descrizioni dei parametri) mostrano i tipi .NET Framework degli oggetti che il parametro accetterà. Il team di PowerShell ha sviluppato questa convenzione per consentire agli utenti di insegnare a .NET Framework.

Scrivere descrizioni dei parametri complete

Le descrizioni dei parametri devono informare gli utenti di due elementi: che cosa fa il parametro (suo effetto) e cosa devono digitare per i valori dei parametri.

Scrivere esempi pratici

Gli esempi dovrebbero mostrare come usare tutti i parametri, ma la cosa più importante consiste nel mostrare come usare il cmdlet nelle attività reali. Iniziare con un semplice esempio e scrivere esempi sempre più complessi. Nell'esempio finale viene illustrato come usare il cmdlet in una pipeline.

Usare il campo Note

Usare il campo Note per spiegare i concetti necessari agli utenti per comprendere il cmdlet. È anche possibile usare le note per aiutare gli utenti a evitare errori comuni. Evitare GLI URL man mano che cambiano. Specificare invece i termini degli utenti per la ricerca.

Testare la Guida

Testare la Guida esattamente come si testa il codice. Chiedere agli amici e ai colleghi di leggere il contenuto della Guida e fornire commenti e suggerimenti. È anche possibile richiedere feedback dai newsgroup.

Vedere anche