ブラウザーで Microsoft Learn ドキュメントを編集する

  • [アーティクル]

ヒント

このトピックでは、マイペースで進められるステップ バイ ステップのラーニング パスを使用できます。

Microsoft のドキュメント セットには、オープン ソースで GitHub 上でホストされているのものがいくつかあります。 すべてのドキュメント セットが完全にオープン ソースであるわけではありませんが、多くには一般公開用のリポジトリが備わっていて、そこで pull request (PR) を使って変更を提案することができます。 このオープンソース アプローチにより、製品エンジニア、コンテンツ チーム、顧客の間のコミュニケーションが効率化され、質の高いものとなります。

クイック編集により、ドキュメント内の小さなエラーや漏れを報告および修正するプロセスが容易化されます。 さまざまな努力を重ねても、公開されたドキュメントには文法やスペルに関する小さな誤りが "必ず" 入り込みます。 これらの問題の特定と修正に関するご協力をお待ちしております。

Microsoft ではすべての変更だけでなく、書き込みアクセス権がある共同作成者に対しても PR を使用します。 ほとんどのリポジトリは既定のブランチを保護しているため、更新プログラムを PR として提出する必要があります。

前提条件

ブラウザーでドキュメントを編集する

  1. 編集するドキュメントに移動します。 一部のドキュメント ページでは、ブラウザー内でコンテンツを直接編集できます。 その場合、以下に示すような [編集] 鉛筆アイコンが表示されます。 [編集] 鉛筆アイコンを選択すると、GitHub のソース ファイルに移動します。

    Screenshot of an Azure documentation article showing the edit pencil icon.

    [編集] ボタンが表示されない場合は、そのコンテンツが公開投稿を受け入れていないことを意味します。 一部のページは (たとえば、コード内のインライン ドキュメントから) 生成され、属しているプロジェクトで編集する必要があります。

  2. GitHub ファイル ページの上部にある鉛筆アイコンを選択します。 鉛筆アイコンが灰色表示されているか、表示されない場合は、GitHub アカウントにログインする必要があります。

    Screenshot of the Azure article within GitHub,showing the edit pencil icon.

    記事の上部には、記事のメタデータがあります。 メタデータは、レポート作成、検索による検出可能性、サイト エクスペリエンスの側面を促進するために記事に適用されます。 公開された記事に対して軽微な更新を行う場合は、メタデータを変更する必要がない場合があります。

  3. このリポジトリで初めて作業する場合は、変更を提案する前にリポジトリをフォークするように求められます。 [このリポジトリをフォークする] を選択して続行します。

  4. Web エディターでファイルを編集します。 ツールバーで [プレビュー] タブを選択して、自分の変更の書式設定を確認します。

  5. 編集が完了したら、通常は画面の右上にある [変更のコミット] または [変更の提案] ボタンを選択します。

  6. コミット メッセージを入力します。 コミット メッセージは PR のタイトルになり、変更の簡単な概要 ("スペルおよび文法エラーの修正" など) にする必要があります。 必要に応じて、詳細な説明を追加して、変更に関する詳細を提供します。 [変更の提案] を選択します。

    Screenshot of the propose changes pop-up.

  7. 変更の提案が済んだため、その変更をリポジトリに "pull" するよう、そのリポジトリの所有者に依頼し、コミットする必要があります。 pull request (PR) を使用してこれを完了します。 [変更の提案] を選択すると、次のようなページが表示されます。

    Screenshot of the comparing changes screen.

    PR は、フォークとブランチ (矢印の右側にある 2 つの項目で表される) からドキュメント リポジトリのメインフォークと main ブランチ (矢印の左側にある 2 つの項目で表される) への変更を提案します。

    選択内容を確認し、[pull request の作成] を選択します。

  8. [pull request を開く] ページで、PR をプレビューします。 必要に応じて、タイトルまたは説明フィールドを変更できます。 準備ができたら、[pull request の作成] を選択します。 このアクションによって PR が開き、変更が提案されたことが記事の所有者に通知されます。

  9. これで完了です。 コンテンツ チームのメンバーが、PR をレビューし、承認されたらそれをマージします。 変更をお願いするフィードバックを受け取る可能性があります。 PR の処理の詳細については、「プル要求を処理する」を参照してください。

制限事項

  • ほとんどのローカライズされた (つまり、翻訳された) コンテンツには、GitHub で編集する機能を備えていません。 ただし、ページの上部にある [フィードバック] (親指) ボタンを選択して [翻訳品質理由] を選ぶと、翻訳品質に関するフィードバックを提供できます。 [フィードバックの提供] フォームを使用して、ローカライズされたコンテンツに関するより具体的なフィードバックを残すこともできます。
  • ブラウザー内の編集操作は、マイナー変更や頻度の低い変更に最適です。 大規模な投稿を行う場合、または Git の高度な機能 (ブランチ管理や高度なマージ競合の解決など) を使用する場合は、リポジトリをフォークしてローカルで作業することをお勧めします。