Aggiornamenti per una nuova esperienza con la documentazione di PowerShell

Questo articolo è stato scritto da Jeff Sandquist, General Manager del team Azure Growth and Ecosystem.

Oggi abbiamo lanciato la nostra esperienza di Azure PowerShell rinnovata per docs.microsoft.com. I miglioramenti di questa esperienza includono il controllo delle versioni del modulo, l'evidenziazione della sintassi nel codice, un sommario più semplice da consultare, la possibilità di modificare e migliorare la documentazione e altro ancora. Dai commenti e suggerimenti dei clienti è risultato chiaro che il contenuto relativo a PowerShell rappresenta un'area di miglioramento e questo è il passaggio successivo del nostro impegno per migliorare la qualità del contenuto. Abbiamo iniziato con Azure, ma tutto il contenuto relativo a PowerShell verrà trasferito a questa esperienza nei prossimi mesi.

Riferimento unificato ai moduli di PowerShell

L'obiettivo della documentazione di riferimento per i moduli di PowerShell è offrire un'esperienza unificata per tutti i moduli di PowerShell rilasciati da Microsoft. ad esempio:

• Modelli URL coerenti: se si conosce il nome del modulo o il relativo cmdlet, è facile risalire all'URL corrispondente. Lo schema di URL usato in Docs è: docs.microsoft.com/powershell/module/{nome-modulo}/{nome-cmdlet}/. Per il cmdlet Get-AzureRMStorageAccount disponibile nel modulo AzureRM.Storage, l'URL sarà: https://docs.microsoft.com/powershell/module/azurerm.storage/get-azurermstorageaccount
• Esperienza utente coerente: la formattazione per i moduli, i cmdlet e gli esempi è ora la stessa per l'intera esperienza della documentazione di PowerShell.
• Contributi facili: gli utenti di PowerShell possono aggiungere esempi di codice o modificare la documentazione di riferimento facendo clic sul pulsante Modifica direttamente nella pagina della documentazione.
• Supporto per il controllo delle versioni per le versioni precedenti di PowerShell: è possibile usare un selettore della versione incluso nella pagina per filtrare la documentazione in base a una versione specifica di Azure PowerShell.

Controllo versioni di PowerShell

Per quanto riguarda il controllo delle versioni per un modulo specifico, alcuni moduli vengono forniti come gruppo di altri moduli, ognuno con uno schema di controllo delle versioni specifico separato. Ad esempio, i clienti scaricano Azure PowerShell tramite PowerShellGet. In passato, i clienti dovevano individuare manualmente quale versione della documentazione si applicava alla loro installazione. Ad esempio, se si era installato Azure PowerShell 3.7, era necessario conoscere ogni singolo modulo fornito da AzureRM 3.7 con AzureRM.Automation 2.7 e AzureRM.CognitiveServices v0.5.0 e cercare la documentazione corrispondente.

Con la nuova esperienza è ora sufficiente scegliere una sola versione e i moduli corretti per la versione installata verranno filtrati automaticamente.

Sommario migliorato

Oltre alle informazioni di riferimento sui cmdlet, sono stati aggiunti panoramiche, procedure per l'installazione, guide introduttive ed esempi. Per le informazioni di riferimento di Azure, inoltre, i cmdlet sono stati raggruppati in base al servizio di Azure.

Filtrare facilmente il contenuto durante la digitazione dal sommario

È possibile filtrare facilmente il sommario a sinistra durante la digitazione, per individuare i cmdlet o i servizi corrispondenti al nome digitato.

Miglioramenti alla pagina dei cmdlet

Colorazione e formattazione migliorate

I cmdlet di PowerShell sono ora colorati e formattati per una migliore leggibilità.

Miglioramenti ai parametri

L'elenco precedente dei parametri non era ordinato perché i parametri venivano divisi in due gruppi, obbligatori o facoltativi. Per questo motivo, sono state aggiunte intestazioni di sezione per raggruppare i parametri obbligatori e facoltativi e sono stati migliorati la colorazione e lo stile per i nomi di parametri.

Comportamento di copia/incolla più efficace

Molti esempi di codice per i cmdlet di PowerShell sono preceduti dal prefisso PS C:\>. Quando si fa clic sul pulsante Copia per l'esempio di codice, viene ora eliminato il prefisso PS C:\>, come mostrato nello screenshot del Blocco note di seguito.

Commenti e suggerimenti

Speriamo che possiate apprezzare i miglioramenti significativi in questa versione.