次の方法で共有

PowerShell コマンドレットのヘルプの記述

  • [アーティクル]

PowerShell コマンドレットは役に立ちますが、ヘルプ トピックでコマンドレットの機能と使用方法が明確に説明されていない限り、コマンドレットが使用されない場合や、さらに悪いことに、ユーザーに不満を感じる可能性があります。 XML ベースのコマンドレットのヘルプ ファイル形式では一貫性が向上しますが、大きなヘルプにはさらに多くの情報が必要です。

コマンドレットのヘルプを作成したことがない場合は、次のガイドラインを確認してください。 コマンドレットのヘルプ トピックを作成するために必要な XML スキーマについては、次のセクションで説明します。 コマンドレット ヘルプ ファイル の作成から始めます。 このトピックには、最上位レベルの XML ノードの説明が含まれています。

コマンドレット ヘルプのガイドラインの作成

書き込みウェル

適切に記述されたトピックに代わるものはありません。 プロのライターでない場合は、役に立つライターまたはエディターを見つけます。 別の方法として、ヘルプ テキストを Microsoft Word にコピーし、文章校正とスペル チェックを使用して作業を改善することもできます。

単純な書き込み

単純な単語と語句を使用します。 専門用語は避けてください。 多くの読者には、外国語辞書とヘルプ トピックのみが用意されているとします。

一貫して書き込む

関連するコマンドレットのヘルプは似ている必要があります (たとえば、Get-Content と Set-Content)。 強制 や InputObject など、標準パラメーターの標準の説明を使用します。 (コア コマンドレットのヘルプからコピーします)。標準の用語を使用します。 たとえば、"argument" ではなく "parameter" を使用し、"command" または "command-let" ではなく "コマンドレット" を使用します。

動詞を使用して概要を開始する

synopsis フィールドは、コマンドレットの内容や動作ではなく、コマンドレットが何を行うかをユーザーに通知します。 動詞は、このコマンドレットが要件を満たしているかどうかをユーザーに通知するタスク ベースのステートメントを作成します。 "get"、"create"、"change" などの単純な動詞を使用します。"set" は避けてください。これはあいまいで、"modify" のような豪華な単語になる可能性があります。

オブジェクトにフォーカスする

ほとんどの "get" コマンドレットでは何かが表示されますが、主な機能はオブジェクトを取得することです。 ヘルプでオブジェクトに焦点を当てて、既定の表示が多くの表示の 1 つであり、さまざまな方法で取得したオブジェクトのメソッドとプロパティを使用できることをユーザーが理解できるようにします。

詳細な説明を記述する

コマンドレットで実行できるすべての操作を、詳細な説明で簡単に一覧表示します。 main 関数で 1 つのプロパティを変更するが、コマンドレットですべてのプロパティを変更できる場合は、詳細な説明でこれを一覧表示します。

従来の構文を使用する

Windows および Unix のコマンド ライン ヘルプで一般的な標準の Backus-Naur 形式を使用します。

パラメーター値に Microsoft .NET 型を使用する

パラメーター値のプレースホルダー (構文とパラメーターの説明) は、パラメーターが受け入れるオブジェクトの .NET Framework 型を示しています。 PowerShell チームは、.NET Framework についてユーザーに教えるのに役立つこの規則を開発しました。

パラメーターの完全な説明を記述する

パラメーターの説明は、パラメーターが何を行うか (その効果) と、パラメーター値に対して何を入力する必要があるかという 2 つのことをユーザーに通知する必要があります。

実際の例を記述する

例では、すべてのパラメーターを使用する方法を示す必要がありますが、最も重要なことは、実際のタスクでコマンドレットを使用する方法を示す点です。 簡単な例から始めて、ますます複雑な例を記述します。 最後の例では、パイプラインでコマンドレットを使用する方法を示します。

[メモ] フィールドを使用する

ユーザーがコマンドレットを理解するために必要な概念を説明するには、[メモ] フィールドを使用します。 また、ユーザーが一般的なエラーを回避するのに役立つメモを使用することもできます。 URL が変更されるのを避けます。 代わりに、検索する用語をユーザーに指定します。

ヘルプをテストする

コードをテストするのと同じように、ヘルプをテストします。 友人や同僚にヘルプ コンテンツを読んでもらい、フィードバックを提供してもらう。 また、ニュースグループからのフィードバックを要請することもできます。

こちらもご覧ください