次の方法で共有

品質改善への貢献

投稿する対象の専門家やドキュメントの専門家である必要はありません。 ドキュメントを改善する機会がある場合は、提案された改善を含む pull request を送信します。 このガイドでは、誰でもドキュメントに品質の向上を貢献できるいくつかの簡単な方法について説明します。

Microsoft では、次の品質領域に重点を置いています。

コード サンプルの書式設定

すべてのコード サンプルは、PowerShell コンテンツの スタイル ガイドライン に従う必要があります。 これらのルールは、便宜上、ここでは省略形で繰り返されます。

  • すべてのコード ブロックは、トリプル バックティック コード フェンス (```) に含める必要があります。
  • コード ブロックの行長は、コマンドレットリファレンス記事の 90 文字に制限されています。
  • コード ブロックの行長は、76アーティクルのabout_*文字に制限されます。
  • PowerShell コード例では、行連結文字 (`) を使用しないでください。
    • パイプ (|) 文字や波括弧 (})、括弧 (()、角括弧 ([) の後など、分割代入や自然な改行ポイントを利用して、行の長さを制限します。
  • コードがコピー貼り付けを目的としていない例を示す PowerShell プロンプトのみを含めます。
  • エイリアスを明示的にドキュメント化しない限り、例でエイリアスを使わないでください。
  • 位置指定パラメーターは使用しないでください。 パラメーターが位置指定の場合でも、パラメーター名を使用します。

書式設定コマンドの構文

すべての散文は、PowerShell コンテンツの スタイル ガイドライン に従う必要があります。 これらの規則は、便宜上ここで繰り返されます。

  • コマンドレットとパラメーターには常にフル ネームを使用します。 エイリアスを具体的に示す必要がある場合以外は、エイリアスの使用を避けてください。
  • プロパティ、パラメーター、オブジェクト、型名、クラス名、クラス メソッドは 太字にする必要があります。
    • プロパティとパラメーターの値は、バックティック (`) でラップする必要があります。
    • 型を角かっこで囲まれたスタイルで参照する場合は、逆引用符を使用します。 例: [System.Io.FileInfo]
  • PowerShell モジュール名は 太字にする必要があります。
  • PowerShell のキーワードと演算子はすべて小文字にする必要があります。
  • コマンドレット名とパラメーターには、Pascal 方式の記法を使用します。
  • 名前でパラメーターを参照する場合、名前は 太字にする必要があります。
  • 構文を示す場合は、ハイフンでパラメーター名を使用します。 パラメーターをバックティックでラップします。
  • 外部コマンドの使用例を示す場合、例はバックティックで囲む必要があります。 常に外部コマンドのファイル拡張子を含めます。

ドキュメントのマークダウン ソースの保守性と読みやすさのために、インライン リンクではなくリンク参照を使用するように概念的なドキュメントを変換しています。

たとえば、次の表記の代わりに、

The [Packages tab](https://www.powershellgallery.com/packages) displays all available
packages in the PowerShell Gallery.

次のようになります。

The [Packages tab][01] displays all available packages in the PowerShell Gallery.

注

インラインリンクを置き換える際には、コンテンツが100文字で折り返されるように調整してください。 reflow-markdown VS Code 拡張機能を使用すると、段落をすばやくリフローできます。

ファイルの下部に、リンクの定義の前にマークダウン コメントを追加します。

<!-- Link references -->
[01]: https://www.powershellgallery.com/packages

次のことを確認してください。

  1. すべてのリンクが正しい場所を指しています。
  2. リンク参照定義を複製しないでください。 URL のリンク参照定義が既に存在する場合は、新しい参照を作成するのではなく、既存の参照を再利用します。
  3. リンク参照定義は、マークダウン コメントの後のファイルの一番下にあり、数値順です。

Markdownリントチェック

参加しているリポジトリのいずれかの記事については、VS Code で記事を開くと、リンティングの警告が表示されます。 次の点を除き、検出された警告のいずれかに対処します。

  • MD022/blanks-around-headings/blanks-around-headers は、コマンドレットリファレンスドキュメントのSynopsisヘッダーに対してです。 これらの項目の場合、規則違反は、ドキュメントが PlatyPS で正しくビルドされるように意図的に行われます。

行の長さを確認し、 Reflow Markdown 拡張機能を使用して長い行を修正します。

スペリング

最善を尽くしたにもかかわらず、入力ミスやスペルミスが紛れ込んでしまい、最終的にドキュメントに残ってしまいます。 これらの間違いにより、ドキュメントのフォローとローカライズが難しくなります。 これらの間違いを修正すると、特に正確な翻訳に依存する英語以外の話者にとって、ドキュメントがより読みやすくなります。

  • Last updated on