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

[アーティクル]
09/25/2021

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

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

コマンドレットヘルプの記述ガイドライン

書き込み方法

何も、十分に記述されたトピックを置き換える必要があります。プロのライターではない場合は、役立つライターまたはエディターを探してください。別の方法として、ヘルプテキストを Microsoft Wordにコピーし、文法とスペルチェックを使用して作業を改善します。

単純に記述する

単純な単語とフレーズを使用します。専門的な用語を使わない。多くの閲覧者には、外部言語辞書とヘルプトピックのみを備えたとします。

一貫した書き込み

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

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

[概要] フィールドは、コマンドレットの動作や動作ではなく、ユーザーに通知します。動詞は、このコマンドレットが要件を満たした場合にユーザーに通知するタスクベースのステートメントを作成します。 "get"、"create"、"change" のような単純な動詞を使用します。 "set" は避け、"modify" のようなあいまいで空想的な単語になる可能性があります。

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

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