PowerShell ドキュメントへの投稿を開始する

この記事では、PowerShell ドキュメントの共同作成者として作業を開始する方法の概要を説明します。

PowerShell-Docs の構造

PowerShell-Docs リポジトリには、次の 3 つのカテゴリのコンテンツがあります。

• リファレンス コンテンツ
• 概念的な内容
• メタデータと構成ファイル

リファレンス コンテンツ

リファレンス コンテンツは、PowerShell に付属するコマンドレットの PowerShell コマンドレット リファレンスです。 コマンドレット 参照 は、バージョン管理されたフォルダー (5.1、7.4、7.5、7.6 など) に収集されます。このフォルダーには、PowerShell に付属するモジュールの参照が含まれています。 また、このコンテンツは、Get-Help コマンドレットによって表示されるヘルプ情報の作成にも使用されます。

概念的コンテンツ

概念ドキュメントは、バージョン別に整理されていません。 PowerShell のすべてのバージョンのすべての記事が表示されます。

メタデータ ファイル

このプロジェクトには、いくつかの種類のメタデータ ファイルが含まれています。 メタデータ ファイルは、ビルド ツールと発行システムの動作を制御します。 これらのファイルの変更は、PowerShell-Docs の保守管理者と承認された共同作成者のみが許可されます。 メタ ファイルを変更する必要がある場合は、問題を開いて必要な変更について話し合います。

リポジトリのルートにあるメタ ファイル

• .* - リポジトリのルートにある構成ファイル
• *.md - リポジトリのルートにあるプロジェクト ドキュメント
• *.yml - リポジトリのルートにあるプロジェクト ドキュメント
• .devcontainer/* - devcontainer 構成ファイル
• .github/**/* - GitHub テンプレート、アクション、およびその他のメタ ファイル
• .vscode/**/* - VS Code 拡張機能の構成
• assets/* - ドキュメントでリンクされているダウンロード可能なファイルが含まれています。
• redir/* - リダイレクト マッピング ファイルが含まれています。
• tests/* - ビルド システムで使用されるテスト ツール
• tools/* - ビルド システムで使用されるその他のツール

ドキュメント セット内のメタ ファイル

• reference/**/*.json - ドックセット構成ファイル
• reference/**/*.yml - TOC およびその他の構造化コンテンツ ファイル
• reference/bread/* - 階層リンク ナビゲーションの構成
• reference/includes/* - マークダウン インクルード ファイル
• reference/mapping/* - バージョン マッピングの構成
• reference/**/media/** - ドキュメントで使用される画像ファイル
• reference/module/* - [モジュール ブラウザー] ページの構成

新しい記事の作成

投稿する新しいドキュメントの GitHub イシューを作成する必要があります。 既存のイシューを調べて、作業が重複していないことを確認します。 割り当てられた問題は in progress と見なされます。 イシューで共同作業を行う場合は、そのイシューに割り当てられているユーザーに連絡します。

POWERShell RFC プロセスと同様に、問題を作成してから、コンテンツを記述します。 この問題により、PowerShell-Docs チームによって拒否される作業に無駄な時間と労力を欠けないようにします。 この問題により、コンテンツの範囲や、PowerShell ドキュメント内の適切な場所について相談できます。 すべての記事は目次に含める必要があります。 提案された TOC の場所は、問題の話し合いに含める必要があります。

既存の記事の更新

該当する場合、コマンドレットの参照記事は、このリポジトリに保持されているすべてのバージョンの PowerShell で重複します。 コマンドレット参照記事または About_ 記事に関する問題を報告する場合は、問題のある記事のバージョンを一覧表示します。

ファイルの各バージョンに適切な変更を適用します。

ローカライズされたコンテンツ

PowerShell ドキュメントは英語で記述され、そのほかに 17 の言語に翻訳されています。 英語のコンテンツは、MicrosoftDocs/PowerShell-Docs という名前の GitHub リポジトリに格納されています。 翻訳されたコンテンツで見つかった問題は、このリポジトリに送信する必要があります。

すべての翻訳は、英語のコンテンツから翻訳されています。 人間による翻訳と機械翻訳の両方を使用しています。

機械翻訳によって翻訳されたコンテンツが、必ずしも正しい単語の選択と文法につながるとは限りません。 記事の技術的な詳細ではなく、任意の言語の翻訳でエラーが見つけた場合は、翻訳が間違っていると思われる理由が説明された問題を開きます。

一部の翻訳の問題は、英語のソース ファイルを変更することで修正できます。 ただし、一部の問題では、社内翻訳システムの更新が必要な場合があります。 このような場合は、レビューと対応のために、社内のローカライズ チームに問題を提出する必要があります。

次のステップ

GitHub で変更を送信する一般的な方法は 2 つあります。 どちらの方法も、中央共同作成者ガイドで説明されています。

1. GitHub Web インターフェイスの既存のドキュメントはを簡単に編集できます。
2. 新しい記事の追加、複数のファイルの更新、その他の大きな変更には、完全な GitHub ワークフローを使用します。

変更を開始する前に、PowerShell-Docs リポジトリのフォークを作成する必要があります。 変更は、PowerShell-Docs のコピーの作業ブランチで行う必要があります。GitHub で クイック編集 方法を使用している場合は、これらの手順が自動的に処理されます。 完全な GitHub ワークフローを使用する場合は、ローカルで作業するためのセットアップが必要です。

どちらの方法も、プル リクエスト (PR) の作成で終了します。 詳細とベスト プラクティスについては、「 pull request の送信」を参照してください。