PowerShell ドキュメントエクスペリエンスの更新

[アーティクル]
06/21/2023

この記事は、Azure 展開およびエコシステムチームの統括部長、Jeff Sandquist によって執筆されました。

docs.microsoft.com の Azure PowerShell のエクスペリエンスが改善されました。改善点には、モジュールのバージョン管理、コード構文の強調表示、移動しやすくなった目次、ドキュメントの編集および改善機能などが含まれます。お客様からのフィードバックにより、PowerShell のコンテンツに改善の余地があることがわかりました。ここからさらに、コンテンツの品質改善を進めていきます。まず Azure から着手しましたが、今後数か月で PowerShell の全コンテンツのエクスペリエンスを同様に改善します。

統合 PowerShell モジュールのリファレンス

PowerShell モジュールのリファレンスドキュメントの目的は、Microsoft で出荷したすべての PowerShell モジュールに単一のエクスペリエンスを提供することです。これには次のものが含まれます

一貫した URL パターン - モジュールの名前やそのコマンドレットがわかっている場合は、URL がわかります。 Docs で使用している URL パターンは、docs.microsoft.com/powershell/module/{module-name}/{cmdlet-name}/ です。 AzureRM.Storage モジュールにある Get-AzureRMStorageAccount コマンドレットの場合、URL は https://docs.microsoft.com/powershell/module/azurerm.storage/get-azurermstorageaccount になります
一貫したユーザーエクスペリエンス - モジュール、コマンドレット、サンプルの書式設定が、同じ PowerShell ドキュメントエクスペリエンス全体で同じになりました。
コントリビューションが簡単に - PowerShell ユーザーはドキュメントページ上で直接 [編集] ボタンをクリックして、コードサンプルの追加やリファレンスドキュメントの編集ができます。
以前のバージョンの PowerShell のバージョン管理をサポート - 特定のバージョンの Azure PowerShell でフィルター処理するには、ページ内バージョンピッカーを使用します。

PowerShell のバージョン管理

特定のモジュールのバージョン管理について説明しましたが、一部のモジュールは他のモジュールのグループとして出荷されていて、各モジュールが個別のバージョン管理のスキームを所有しています。たとえば、お客様が Azure PowerShell をダウンロードするときには PowerShellGet を使用します。かつては、どのバージョンのドキュメントが自分のインストールに適用されるのかをお客様が自分で判別しなくてはなりませんでした。たとえば、Azure PowerShell 3.7 をインストールした場合、AzureRM 3.7 には AzureRM.Automation 2.7 および AzureRM.CognitiveServices v0.5.0 が付属していることを把握し、該当するドキュメントを探す必要がありました。

新しいエクスペリエンスでは、1 つのバージョンを選ぶだけで、インストールしたバージョンに基づいて正しいモジュールがフィルター処理されます。