Microsoft Learn ドキュメント共同作成者ガイドの概要
Microsoft Learn ドキュメント共同作成者ガイドへようこそ。
Microsoft Learn で専門知識を他のユーザーと共有することで、すべてのユーザーがより多くのことを達成するのに役立ちます。 このガイドの情報を使用して、Microsoft Learn に新しい記事を公開するか、既存の発行済み記事を更新します。
Microsoft のドキュメント セットには、オープン ソースで GitHub 上でホストされているのものがいくつかあります。 すべてのドキュメント セットが完全にオープン ソースであるわけではありませんが、多くには一般公開用のリポジトリが備わっていて、そこで pull request (PR) を使って変更を提案することができます。 このようなオープン ソースのアプローチにより、製品エンジニア、コンテンツ チーム、およびお客様との間のコミュニケーションが合理化され、改善されます。また、その他の利点があります。
- オープンソースのリポジトリにより "一般公開された状態で計画を行う" ことで、最も必要とされているドキュメントがどれであるかについてのフィードバックを得る。
- オープンソースのリポジトリにより "一般公開された状態でレビューを行う" ことで、最も役に立つコンテンツを最初のリリースで公開する。
- オープンソースのリポジトリにより "一般公開された状態で更新を行う" ことで、コンテンツの継続的な改善を容易にする。
Microsoft Learn のユーザー エクスペリエンスは、 GitHub ワークフローを直接統合して、さらに簡単にします。 まずは表示しているドキュメントを編集してみましょう。 または、新しいトピックをレビューして支援するか、品質に関するイシューを作成します。
重要
Microsoft Learn に発行されるすべてのリポジトリでは、 Microsoft オープン ソース行動規範 または .NET Foundation 行動規範が採用されています。 詳細については、倫理規定に関する FAQ のページを参照してください。 ご質問や意見がある場合は、opencode@microsoft.com または conduct@dotnetfoundation.org までご連絡ください。
パブリック リポジトリ内のドキュメントとコード例に対する軽微な修正または説明については、 learn.microsoft.com 利用規約の対象となります。 お客様が Microsoft の従業員ではない場合、新規または大幅な変更を加えると、オンラインの共同作成使用許諾契約書 (CLA) のご提出をお願いするコメントが PR 内に生成されます。 このオンライン フォームにご入力いただいてから、お客様の PR に対するレビューや承認を実施いたします。
ドキュメントのクイック編集
クイック編集により、ドキュメント内の小さなエラーや漏れを報告および修正するプロセスが合理化されます。 さまざまな努力を重ねても、公開されたドキュメントには文法やスペルに関する小さな誤りが "必ず" 入り込みます。 イシューを作成して間違いを報告することもできますが、利用可能な場合は、PR を作成して問題を修正するオプションの方が速くて簡単です。
一部のドキュメント ページでは、ブラウザー内でコンテンツを直接編集できます。 その場合、以下に示すような [編集] ボタンが表示されます。 [編集] (または同等にローカライズされた) ボタンを選択すると、GitHub 上のソース ファイルに移動します。
[編集] ボタンが表示されない場合は、そのコンテンツが公開投稿を受け入れていないことを意味します。 一部のページは (たとえば、コード内のインライン ドキュメントから) 生成され、属しているプロジェクトで編集する必要があります。
鉛筆アイコンを選択して記事を編集します。 鉛筆アイコンが灰色表示されている場合は、自分の GitHub アカウントにログインするか、新しいアカウントを作成する必要があります。
Web エディターでファイルを編集します。 [プレビュー] タブを選択して、自分の変更の書式設定を確認します。
編集が完了したら、ページの下部までスクロールします。 [変更の提案] 領域に、変更のタイトルと、必要に応じて説明を入力します。 タイトルはコミット メッセージの最初の行になります。 [ 変更の提案] を選択してフォークに新しいブランチを作成し、変更をコミットします。
変更の提案が済んだため、その変更をリポジトリに "pull" するよう、そのリポジトリの所有者に依頼し、コミットする必要があります。 これを完了するには、"pull request" (PR) と呼ばれる作業を実行します。 [Propose changes](変更の提案) を選択すると、次のような新しいページが表示されます。
[pull request の作成] を選択します。 次に、PR タイトル、説明を入力し、[Pull Request の作成] を選択します。 GitHub を初めてお使いの場合、詳細については「 pull request について」を参照してください。
これで完了です。 コンテンツ チームのメンバーが、PR をレビューし、承認されたらそれをマージします。 変更をお願いするフィードバックを受け取る可能性があります。
GitHub の編集用 UI は、リポジトリに対する自分のアクセス許可に対応しています。 上の図は、対象のリポジトリに対する書き込みアクセス許可がない共同作成者の場合です。 GitHub により、対象のリポジトリのフォークが自分のアカウント内に自動的に作成されます。 新しく作成されたフォーク名には、既定でフォーム GitHubUsername/RepositoryName があります。 対象のリポジトリへの書き込みアクセス権がある場合は、GitHub により対象のリポジトリに新しいブランチが作成されます。 ブランチ名は patch-n という既定の形式になり、パッチのブランチ用の数値識別子が使われます。
Microsoft ではすべての変更だけでなく、書き込みアクセス権がある共同作成者に対しても PR を使用します。 ほとんどのリポジトリに保護された既定のブランチがあるため、更新プログラムを PR として提出する必要があります。
ブラウザー内の編集操作は、軽微または頻度の低い変更を行う場合に最適です。 大規模な共同作成を行う場合、または Git の高度な機能 (ブランチ管理や高度なマージ競合の解決など) を使用する場合は、リポジトリをフォークしてローカルで作業する必要があります。
注意
ほとんどのローカライズされたドキュメントは、GitHub を介してフィードバックを送信したり編集したりする機能を備えていません。 ローカライズされたコンテンツに関するフィードバックを提供するには、フォームを使用 https://aka.ms/provide-feedback します。
オープン中の PR をレビューする
オープン中の PR キューを確認することで、新しいトピックを公開前に読むことができます。 レビューは GitHub フローのプロセスに従います。 提案された更新内容や新しい記事をパブリック リポジトリ内で閲覧できます。 それらをレビューしてコメントを追加します。 Microsoft Learn リポジトリのいずれかを確認し、開いている PR で関心のある領域を確認します。 提案された更新内容に対するコミュニティのフィードバックは、コミュニティ全体の役に立ちます。
品質に関するイシューを作成する
Microsoft のドキュメントは、進行中の継続的な作業です。 適切なイシューは、コミュニティの最優先事項に注力するために役立ちます。 提供していただく情報が詳細なほど、イシューは役立つものになります。 お探しだった情報を教えてください。 ご使用になった検索語句を教えてください。 初めてお使いいただくテクノロジについてどう使い始めたらよいのかが不明瞭だった場合、どのようにするのが望ましいかをお聞かせください。
Microsoft のドキュメント ページの多くには、ページの下部に [フィードバック] セクションがあります。これを選択して製品のフィードバックまたはコンテンツに関するフィードバックを入力し、その記事に固有のイシューを追跡することができます。
イシューによって、何が必要とされているかについての会話が開始されます。 コンテンツ チームでは、追加できる内容のご提案を含めてこのようなイシューに回答し、ご意見を伺います。 ドラフトを作成し次第、お客様に PR のレビューを依頼いたします。
さらに深く関わる
このガイドのその他のトピックは、Microsoft Learn への生産的な貢献を開始するのに役立ちます。 Microsoft Learn コンテンツで使用される GitHub リポジトリ、Markdown ツール、拡張機能の操作について説明します。