Mises à jour de l’expérience de notre documentation PowerShell

Cet article a été écrit par Jeff Sandquist, Directeur Général de la division Azure Growth and Ecosystem.

Aujourd’hui, nous avons lancé notre version revisitée de l’expérience Azure PowerShell pour docs.microsoft.com. Améliorations apportées à cette expérience : gestion des versions des modules, coloration syntaxique du code, table des matières facile à parcourir, possibilité de modifier et d’améliorer la documentation, et plus encore. Sur la base des commentaires des clients, nous savons que le contenu PowerShell nécessite des améliorations, c’est pourquoi notre prochaine étape consiste précisément à améliorer la qualité de notre contenu. Nous avons commencé par Azure et nous allons poursuivre en appliquant la même expérience à l’ensemble de notre contenu PowerShell dans les prochains mois.

Centralisation des références des modules PowerShell

Pour nos documentations de référence des modules PowerShell, notre objectif consiste à offrir une expérience unifiée pour tous les modules PowerShell livrés par Microsoft. Les opérations à effectuer sont les suivantes :

  • Des modèles d’URL cohérents : Si vous connaissez le nom du module ou d’une applet de commande, vous connaissez l’URL. Le modèle d’URL que nous utilisons sur Docs est le suivant : docs.microsoft.com/powershell/module/{nom-module}/{nom-applet de commande}/. Pour l’applet de commande Get-AzureRMStorageAccount qui est dans le module AzureRM.Storage, l’URL sera : https://docs.microsoft.com/powershell/module/azurerm.storage/get-azurermstorageaccount
  • Une expérience utilisateur cohérente : La mise en forme des modules, des applets de commande et des exemples est maintenant la même dans l’ensemble de la documentation PowerShell.
  • Des contributions faciles : Les utilisateurs PowerShell peuvent ajouter des exemples de code ou modifier notre documentation de référence en cliquant sur le bouton Modifier directement dans la page de documentation.
  • Une prise en charge de la gestion des versions précédentes de PowerShell : Pour filtrer sur une version spécifique d’Azure PowerShell, utilisez notre sélecteur de version qui est intégré aux pages.

Gestion des versions PowerShell

Nous venons de mentionner la gestion des versions d’un module spécifique, mais certains modules sont livrés dans un groupe d’autres modules, chacun ayant son propre système de version. Par exemple, les clients téléchargent Azure PowerShell via PowerShellGet. Avant, les clients devaient trouver manuellement les versions de la documentation qui s’appliquaient à leur installation. Par exemple, si vous aviez installé Azure PowerShell 3.7, vous deviez connaître chaque module qu’AzureRM 3.7 avait livré avec AzureRM.Automation 2.7 et AzureRM.CognitiveServices v0.5.0 et rechercher cette documentation.

Avec notre nouvelle expérience, il vous suffit de sélectionner une version et nous filtrons les modules correspondants en fonction de ce que vous avez installé.

PowerShell version selection

Amélioration de la table des matières

En plus des informations de référence sur les applets de commande, nous avons ajouté le contenu de présentation, les étapes d’installation, le démarrage et les exemples. Pour les informations de référence sur Azure, nous avons aussi regroupé les applets de commande basées sur le service Azure.

Table of contents showing overview, samples, reference

Filtrage facile en cours de frappe - à partir de la table des matières

Vous pouvez facilement filtrer la table des matières de gauche à mesure que vous tapez pour retrouver les applets de commande ou les services correspondants.

Results filter as you type

Améliorations des pages d’applet de commande

Amélioration de la colorisation et de la mise en forme

Les applets de commande PowerShell sont maintenant colorisées et mises en forme pour mieux les lire.

Colorized PowerShell syntax

Améliorations des paramètres

Quand nous avons regroupé les paramètres selon s’ils sont obligatoires ou facultatifs, la liste des paramètres est restée dans le désordre. Nous avons donc ajouté des titres de section pour regrouper les paramètres obligatoires et les paramètres facultatifs, et amélioré le style/la colorisation des noms de paramètre.

Grouping required and optional parameters

Comportement simplifié du copier/coller

Certains exemples de code de nos applets de commande PowerShell sont préfixés avec le texte PS C:\>. Quand vous cliquez sur le bouton Copier pour l’exemple de code, le préfixe PS C:\> n’apparaît plus, comme illustré dans la capture d’écran du Bloc-notes ci-dessous.

Copy button removing text

Vos commentaires

Nous espérons que vous verrez des améliorations significatives dans cette version. Nous n’avons pas encore terminé notre projet, donc n’hésitez pas à nous envoyer vos commentaires via notre Docs UserVoice.