Updates to our PowerShell Documentation Experience

  • Članek

This post was written by Jeff Sandquist, General Manager in the Azure Growth and Ecosystem team.

Today we launched our revamped Azure PowerShell experience for docs.microsoft.com. Improvements to this experience include module versioning, code syntax highlighting, easier-to-navigate table of contents, the ability to edit and improve docs, and more. We know from customer feedback that PowerShell content has been an area for improvement and this is the next step in our journey to improve the quality of our content. We've started with Azure, but will be moving all of our PowerShell content to this experience in the coming months.

Unified PowerShell Module Reference

The goal of our PowerShell Module reference docs is to provide a unified experience for all PowerShell modules shipped at Microsoft. This includes:

  • Consistent URL Patterns - If you know the name of the module or a cmdlet, you know the URL. The URL pattern we are using on Docs is: docs.microsoft.com/powershell/module/{module-name}/{cmdlet-name}/. For the Get-AzureRMStorageAccount cmdlet that is in the AzureRM.Storage module, the URL would be: https://docs.microsoft.com/powershell/module/azurerm.storage/get-azurermstorageaccount
  • Consistent user experience - Formatting for modules, cmdlets, and samples is now the same across the entire PowerShell documentation experience.
  • Easy contributions - PowerShell users can add code samples or edit our reference docs by clicking the Edit button directly on the doc page.
  • Support for versioning for previous versions of PowerShell - To filter on a specific version of Azure PowerShell, use our in-page version picker.

PowerShell Versioning

While we mentioned versioning for a specific module, some modules ship as a group of other modules, each with their own separate versioning scheme. For example, customers download Azure PowerShell through PowerShellGet. In the past customers had to manually decipher which versions of the docs applies to their installation. For example, if you installed Azure PowerShell 3.7, you would have to know each individual module that AzureRM 3.7 ships with AzureRM.Automation 2.7 and AzureRM.CognitiveServices v0.5.0 and look for those docs.

With our new experience you just have one version to pick and we will filter the correct modules based on what you have installed.

PowerShell version selection

Improved table of contents

In addition to cmdlet reference, we added overview content, installation steps, getting started, and samples. For Azure reference, we also grouped cmdlets based on Azure Service.

Table of contents showing overview, samples, reference

Easily filter as you type - from the table of contents

You can easily filter the left TOC as you type for matching cmdlets or services matching that name.

Results filter as you type

Cmdlet page improvements

Improved colorization and formatting

PowerShell cmdlets are now nicely colorized and formatted for better readability.

Colorized PowerShell syntax

Parameter improvements

While we previously grouped parameters by whether they were required or optional, the parameter list appeared unordered. Instead we added section headings to group required parameters and optional parameters and improved the colorization/style for parameter names.

Grouping required and optional parameters

Smarter Copy/Paste behavior

A number of our PowerShell cmdlets code samples are prefixed with the text PS C:\>. When you click the Copy button for the code example, we will now strip away the PS C:\> prefix, as shown in Notepad screenshot below.

Copy button removing text

Your Feedback

We hope that you see significant improvements with this release.