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

  • 5 分

一般的なツールと投稿のバックグラウンドで動く部分の概要を理解したので、ここで Microsoft ドキュメントに小さな投稿を行う具体的な手順を見てみましょう。 記事に小さな変更を加える場合は、まず適切なツールが設定されていることを確認します。 これで、編集を開始し、Microsoft Learn コミュニティの他のメンバーと知識を共有する準備が整います。

ステップ 1: GitHub アカウントを設定する

Microsoft Learn は GitHub ワークフローを統合してコンテンツを更新するため、投稿するには GitHub アカウントが必要です。 GitHub アカウントが既にある場合は、サインインしていることを確認します。

GitHub アカウントがまだない場合は、次の手順に従って作成します。

  1. GitHub に移動します。
  2. [サインアップ] を選択します。
  3. 画面の指示に従ってアカウントを設定します。

ステップ 2: 変更を加える

Microsoft Learn のすべてのコンテンツがパブリック リポジトリに保存されているわけではない点に注意してください。 変更を加える前に、まず、投稿先のコンテンツが公開投稿可能かどうかを確認します。 その場合は、ブラウザーで直接変更できます。

  1. 編集する learn.microsoft.com に関するドキュメント記事に移動します。 記事の上部にある鉛筆型の [編集] アイコンを探して、記事がパブリック リポジトリに保存されているかどうかを確認します。 アイコンが表示されている場合は、公開投稿の対象です。

  2. 鉛筆アイコンの編集を選択します。 これにより、記事が保存されているパブリック GitHub リポジトリ内のソース ファイルに移動します。

    鉛筆の [編集] アイコンが強調表示されているMicrosoft Learn ドキュメント記事のスクリーンショット。

  3. GitHub ファイル ページの上部にある鉛筆アイコンを選択します。 このアイコンには、ファイルが保存されているリポジトリを既にフォークしているかどうかに応じて、[Edit this file in your fork of this project] (このプロジェクトのフォークでこのファイルを編集する) と [Fork this repository and edit the file] (このファイルをフォークしてフォークで編集する) のいずれかのラベルが付けられています。

    このアイコンを選択するには、この時点で GitHub アカウントにサインインしている必要があります。 サインインしていない場合、このオプションは使用できません。

    ドキュメント記事の GitHub ソース ファイルのスクリーンショット。[ファイルの編集] 鉛筆アイコンが強調表示されています。

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

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

  5. ブラウザーに編集インターフェイス、つまり [Edit] (編集) ペインが表示されます。 Markdown というフォーマットの構文で記述された記事が表示されます。 ペインで変更を加えます。

    [編集] ペインで編集できる Markdown 構文で記述されたドキュメント記事が表示されたブラウザーのスクリーンショット。

  6. [編集] ペインの上部にある [プレビュー] タブを選択します。これにより、発行されたフォームで変更を表示して、それらを検証できます。

ステップ 3: pull request を作成する

変更を加えてプレビューを終了したら、pull request (PR) の作成に進みます。 PR は、変更をライブ リポジトリのメイン ブランチにマージして Microsoft Learn に表示されるように提案する方法であることを忘れないでください。 PR は、作業ブランチからの変更をプルして別のブランチにマージするように要求することで、GitHub のコラボレーション モデルを有効にします。 ほとんどの場合、この別のブランチはメイン リポジトリの既定のブランチです。

  1. [変更をコミット] または [変更を提案] ボタンを見つけて選択します。通常はページの上部にあります。

  2. [コミット メッセージ] を追加します。 これが PR のタイトルになります。 コミット メッセージは、変更の簡単な概要にする必要があります。 必要に応じて、詳細な説明を追加して、変更に関する詳細を提供します。

    コミット メッセージの作成と、変更の詳細な説明の追加のための 2 つのフィールドが表示されたポップアップ ボックスのスクリーンショット。

  3. [変更を提案] を選択します。

  4. 次のページでは、変更をマージする場所 (ベースと呼ばれます) を確認するように求められます。 ベースが main であることを確認します。

    共同作成者が変更をマージする宛先リポジトリとブランチを確認する必要がある Web ページのスクリーンショット。[メイン] が [ベース] として選択されています。

  5. [pull request の作成] を選択します。

  6. PR をプレビューします。 タイトルまたは説明フィールドに変更を加えます。

  7. [pull request の作成] ボタンを選択します。 これにより、pull request が開きます。

PR は作成されましたが、まだ送信されていません。 次のステップで、PR をマージするための最終確認手順を完了します。

シナリオ: Azure App Service の記事を編集する

あなたは、Azure App Service に関する特別な専門知識を持つソフトウェア エンジニアであることを思い出してください。 App Service に関するドキュメント記事を確認しているときに、他の人がサービスを使用するのに役立つ詳細を追加したくなったとします。 あなたは、Microsoft Learn に初めて投稿して、自分の知識を共有することにしました。 GitHub アカウントにサインインしたら、投稿プロセスを開始します。