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

  • 5 分

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

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

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

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

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

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

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

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

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

    Screenshot of a Microsoft Learn documentation article with the pencil Edit icon highlighted.

  3. GitHub ファイル ページの上部にある鉛筆アイコンを選択します。 このアイコンには、ファイルが保存されているリポジトリをすでにフォークしているかどうかに応じて、[このリポジトリをフォークしてフォークで編集する] または [このプロジェクトのフォークでこのファイルを編集する] のいずれかのラベルが付けられます。

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

    Screenshot of the GitHub source file for a documentation article. The Edit file pencil icon is highlighted.

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

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

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

    Screenshot of a browser with a documentation article written in Markdown syntax, which can be edited in the Edit pane.

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

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

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

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

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

    Screenshot of the pop up box with two fields to create a Commit message and add an extended description of the changes.

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

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

    Screenshot of the webpage where contributors should verify the destination repository and branch they want to merge changes to. Main is selected as the Base.

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

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

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

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

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

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