品質改善への貢献

Hacktoberfest 2022 では、PowerShell コンテンツの品質改善に貢献するためのプロセスをパイロットしました。 このガイドでは、そのプロセスを一般化して、コミュニティ メンバーがドキュメントの品質を向上させるための低摩擦の方法を定義します。

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

• コード サンプルの書式設定
• 書式設定コマンドの構文
• リンク参照
• Markdown の構文チェック
• スペリング

プロジェクトの追跡

Microsoft では、 PowerShell Docs Quality Contributions GitHub プロジェクトを使用して投稿を追跡しています。

プロジェクト ページには、この作業に関連する問題と PR に関するいくつかのビューがあります。

• [ 問題を開く ] ビューには、開いているすべての問題が表示されます。
• [完了] ビューには、マージされた PR が表示されます。
• PowerShell ビューには、PowerShell-Docs、PowerShell-Docs-DSC、PowerShell-Docs-Modules リポジトリのドキュメントに関する未解決の問題が表示されます。
• Windows PowerShell ビューには、windows-powershell-docs リポジトリのドキュメントに関する未解決の問題が表示されます。
• Azure PowerShell ビューには、azure-docs-powershell リポジトリのドキュメントに関する未解決の問題が表示されます。
• オープンPRビューは、開いているすべてのPRを表示します。

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

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

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

書式設定コマンドの構文

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

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

リンクリファレンス

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

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

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

次のようになります。

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

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

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

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

1. リンクは、ドキュメントに表示される順序で定義されます。
2. すべてのリンクが正しい場所を指しています。
3. リンク参照定義は、マークダウン コメントの後のファイルの下部にあり、正しい順序になっています。

Markdownリントチェック

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

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

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

スペリング

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

プロセス

1 つ以上の品質領域と、改善する記事 (または記事のグループ) を選択することをお勧めします。 作業をガイドするには、次の手順に従います。

1. 重複する作業を回避するために、この作業に関して提出された問題がないか プロジェクト を確認します。

2. 適切なリポジトリで新しい問題を開きます。

   • MicrosoftDocs/PowerShell-Docs リポジトリに、PowerShell リファレンスと概念コンテンツについての問題をオープンする。
   • MicrosoftDocs/PowerShell-Docs-Dsc にDSCコンテンツの問題を開く
   • Crescendo、PlatyPS、PSScriptAnalyzer、SecretManagement、SecretStore コンテンツの MicrosoftDocs/PowerShell-Docs-Modules で問題を開きます。
   • Azure PowerShell コンテンツの MicrosoftDocs/azure-docs-powershell で問題を開きます。
   • Windows PowerShell モジュール コンテンツの MicrosoftDocs/windows-powershell-docs で問題を開きます。

3. 共同作成者のガイドに従って、変更を行うためのセットアップを行います。

4. pull request を送信します。 確保：

   1. PR タイトルには、 Quality: プレフィックスが付いています。

   2. PR 本文は、解決される問題を順序付けされていないリスト アイテムとして参照し、 リンク キーワードの 1 つを使用します。

      たとえば、問題の 123に取り組んでいる場合、PR の本文に次の Markdown が含まれている必要があります。

      - resolves #123
      

   PR を送信すると、保守担当者があなたの作業内容を確認し、一緒にマージするための作業を行います。