Mixed Reality 技術者向けガイドに投稿する

  • [アーティクル]
  • 適用対象:
    Windows 10

この技術者向けガイドに関心をお寄せいただき、ありがとうございます。 お客様からのフィードバック、編集、追加、ドキュメントの改善へのご協力に感謝いたします。このページでは、投稿するための基本的な手順とガイドラインについて説明します。

重要

に learn.microsoft.com 発行されるすべてのリポジトリは、 Microsoft オープン ソースの行動規範を採用しています。 詳細については、倫理規定についてのよくある質問に関するページをご覧いただくか、opencode@microsoft.com 宛てに質問またはコメントを送信してください。

パブリック リポジトリのドキュメントとコード例に関する軽微な修正または説明は、利用規約のlearn.microsoft.com対象となります。 Microsoft の従業員ではない共同作成者が新規または大幅な変更を行うと、オンライン貢献者使用許諾契約書 (CLA) の提出をお願いするコメントが pull request 内に生成されます。 pull request が正しく受理されるように、オンライン フォームへのご記入をお願いいたします。

開始する前に

まだお持ちでない場合は、GitHub アカウントを作成する必要があります。

注意

Microsoft の従業員の場合は、Microsoft オープン ソース ポータルでMicrosoft エイリアスに GitHub アカウントをリンクします。 "Microsoft" および "MicrosoftDocs" 組織に参加します。

GitHub アカウントを設定する場合は、こちらのセキュリティ上の注意事項も推奨されます。

  • GitHub アカウントに強力なパスワードを作成する。
  • 2 要素認証を有効にする。
  • 回復用コードを安全な場所に保存する。
  • パブリック プロファイル設定を更新する。
    • 自分の名前を設定し、[Public email](パブリック メール) を [Don't show my email address](自分のメール アドレスを表示しない) に設定します。
    • 投稿するドキュメント ページにサムネイルが表示されるので、プロフィール画像をアップロードすることをお勧めします。
  • コマンド ラインを使用する予定の場合は、 Git Credential Manager for Windows を設定することを考慮してください。 そうすることで、投稿を行うごとにパスワードを入力する必要がなくなります。

発行システムは GitHub に関連付けられているため、これらの手順が重要です。 自分の GitHub エイリアスを使用して、各記事の作成者または共同作成者として記載されます。

変更する方法

ドキュメントへの変更を提案するには、次の手順に従ってください。 Screenshots (スクリーンショット)
1. 公開された記事を表示しているときに、ページの右上にある [編集 ] ボタンをクリックします。 GitHub リポジトリ内の対応するマークダウン ソース ファイルにリダイレクトされます。 [編集] ボタン
2. GitHub アカウントをまだ持っていない場合は、右上の [Sign Up] をクリックして新しいアカウントを作成します。 [サインアップ] ボタン
3. 対応する GitHub ページが開いたら、編集 (鉛筆アイコン) をクリックします。 鉛筆ボタン
4. [Edit file] ペインで、ファイルのメタデータを更新し、Markdown 言語を使用してコンテンツを変更します。 (Markdown を記述する方法。) ファイルの編集
5. [Preview changes] をクリックして、書式設定が想定どおりに表示されることを確認します。 変更のプレビュー
6. 完了して、ページの一番下までスクロールし、[Propose file change] をクリックすると、[Comparing changes] ページが表示され、変更内容を確認できます。 次に、[Create pull request] ボタンをクリックして、変更を送信します。 これで完了です。 変更を提案する

(pull request を使用して) 変更が送信されると、ドキュメント チームのメンバーによってレビューされます。 要求が受け入れられた場合は、Windows Mixed Reality VR に更新プログラムが発行されます。

*内部レビューの場合のみ、Windows Mixed Reality VR のステージング サイトで変更を確認できます。

メタデータの更新

各記事の上部にあるメタデータを更新します。

  • title: 記事を表示したときにブラウザー タブに表示されるページ タイトル。 ページ タイトルは SEO とインデックス作成に使用されます。そのため、必要な場合を除き、タイトルを変更しないでください (ただ、これはドキュメントが公開される前はそれほど重要ではありません)。
  • description: 記事の内容の簡単な説明を記述します。これは SEO と検出を向上させます。
  • author: ページのプライマリ所有者である場合、ここに GitHub エイリアスを追加します。
  • ms.author: ページのプライマリ所有者である場合、ここに Microsoft エイリアスを追加します (@microsoft.com は必要ありません。エイリアスだけです)。
  • ms.date: ページに主要な内容を追加する場合、日付を更新します。明確化、書式設定、文法、スペルなどの修正の場合は不要です。
  • keywords: キーワードは SEO (検索エンジン最適化) を支援します。 記事に固有のキーワードをコンマとスペースで区切って追加しますが、リスト内の最後のキーワードの後には句読点を付けません。 すべての記事に適用されるグローバル キーワードは、他の場所で管理されているので、追加する必要がありません。

既存の記事の名前変更または削除

変更によって既存の記事が名前変更または削除される場合は、必ずリダイレクトを追加してください。 そうすることで、既存の記事へのリンクを持つユーザーが、引き続き適切な場所に移動します。 リダイレクトは、リポジトリのルートにある .openpublishing.redirection.json ファイルによって管理されます。

.openpublishing.redirection.json へのリダイレクトを追加するには、redirections 配列にエントリを追加します。

{
    "redirections": [
        {
            "source_path": "mixed-reality-docs/enthusiast-guide/old-article.md",
            "redirect_url": "new-article#section-about-old-topic",
            "redirect_document_id": false
        },
    ...
    ]
}
  • source_path は、削除する古い記事への相対リポジトリ パスです。 パスが mixed-reality-docs/enthusiast-guide で始まり .md で終わっていることを確認します。
  • redirect_url は、古い記事から新しい記事への相対パブリック URL です。 この URL には mixed-reality-docs/enthusiast-guide や .md が含まれていないことを確認してください。これはリポジトリ パスではなくパブリック URL を参照するためです。 #section を使用して、新しい記事内のセクションにリンクできます。 また、必要に応じて、 ここで他のサイトへの絶対パスを使用することもできます。
  • redirect_document_id は、前のファイルのドキュメント ID を保持するかどうかを示します。 既定では、 falseです。 リダイレクトされた記事の ms.documentid 属性値を保持する場合は、true を使用します。 ドキュメント ID と、ページ ビューやランキングなどのデータを保持した場合、ターゲット記事に移行されます。 リダイレクトの主な目的が名前変更であり、内容の一部だけが同じである別の記事へのポインターではない場合に、これを行ってください。

リダイレクトを追加する場合、古いファイルを確実に削除してください。

新しい記事の作成

次のワークフローを使用して、Web ブラウザーで GitHub を介してドキュメントのリポジトリに新しい記事を作成します。

  1. (右上の [Fork] ボタンを使用して) MicrosoftDocs/mixed-reality/tree/docs/enthusiast-guide の "main" ブランチからフォークを作成します。

    メイン ブランチをフォークします。

  2. "mixed-reality/enthusiast-guide" フォルダーで、右上にある [Create new file] を選択します。

  3. 記事のページ名を作成し (スペースの代わりにハイフンを使用してください。また、句読点やアポストロフィを使用しないでください)、".md" を追加します。

    新しいページに名前を付けます。

    重要

    必ず、"mixed-reality-docs/enthusiast" フォルダー内から新しい記事を作成してください。 これを確認するには、新しいファイル名の行で "/mixed-reality-docs/enthusiast-guide" を確認します。

  4. 新しいページの上部に、次のメタデータ ブロックを追加します。

    ---
title:
description:
author:
ms.author:
ms.date:
ms.topic: article
keywords:
---

  5. 上記のセクションの手順に従って、関連するメタデータ フィールドに入力します。

  6. Markdown の基礎を使用して記事の内容を書き込みます。

  7. 他の関連記事へのリンクを含む ## See also セクションを記事の下部に追加します。

  8. 完了したら、[Commit new file](新しいファイルをコミットする) を選択します。

  9. [New pull request] を選択し、フォークの 'main' ブランチを MicrosoftDocs/mixed-reality/enthusiast-guide の 'main' にマージします (矢印が正しい方向を指していることを確認してください)。

    フォークから MicrosoftDocs/Mixed-Reality/enthusiast-guide への pull request を作成する

ブランチを操作する

Mixed Reality愛好家ガイド GitHub リポジトリでは、2 つのメイン親ブランチを利用しています。メイン、このコンテンツはステージング サイトで確認できます。ライブ サイトに表示されるコンテンツについては Live です。

投稿をする場合は、Pull Request (PR) を Main ブランチに送信してください。 このブランチはステージング サイトで表示でき、ライブで公開する準備ができている投稿のみを含んでいます。 また、独自の一意のブランチ名を使用してブランチを作成し、送信することもできます。これは、ステージング サイトで選択して表示できます。 (Live ブランチは、コンテンツ管理者のみが使用できます)。

Markdown の基本

次のリソースは、Markdown 言語を使用してドキュメントを編集する方法を学習するのに役立ちます。

テーブルの追加

Microsoft Learn で表のスタイルを設定する方法により、インライン CSS を試しても、罫線やカスタム スタイルは使用されません。 これは短時間は機能しているように見えますが、最終的には、プラットフォームによってテーブルからスタイルが除去されます。 そのため、事前に計画し、テーブルを単純にしておきます。 Markdown テーブルを簡単にするためのサイトはこちらです。

Visual Studio Code 向けの Docs Markdown 拡張機能では、Visual Studio Code (下記参照) を使用してドキュメントを編集する場合にも、テーブルの生成を簡単に行うことができます。

イメージの追加

リポジトリ内の "mixed-reality-docs/images" フォルダーにイメージをアップロードし、記事で適切に参照する必要があります。 イメージは自動的にフルサイズで表示されます。これは、大きなイメージが記事の全体の幅を占めることを意味します。 アップロードする前に、イメージのサイズを事前に設定することをお勧めします。 推奨される幅は、600 から 700 ピクセルです。ただし、情報がぎっしり詰まったスクリーンショットや、スクリーンショットの一部である場合は、サイズを変更する必要があります。

重要

フォークされたリポジトリにイメージをアップロードできるのは、マージする前のみです。 そのため、記事にイメージを追加する予定がある場合は、最初に Visual Studio Code を使用して、そのイメージをフォークの "images" フォルダーに追加するか、Web ブラウザーで次の操作を行ったことを確認する必要があります。

  1. MicrosoftDocs/Mixed-Reality のリポジトリをフォークした。
  2. フォーク内の記事を編集した。
  3. 記事で参照しているイメージを、フォーク内の "mixed-reality-docs/images" フォルダーにアップロードした。
  4. フォークを MicrosoftDocs/mixed-reality の "main" ブランチにマージする Pull Request を作成した。

独自にフォークしたリポジトリを設定する方法については、「新しい記事の作成」の手順に従ってください。

作業のプレビュー

Web ブラウザーを使用して GitHub を編集しているときに、ページの上部の近くにある[Preview](プレビュー) タブを選択して、コミットする前に作業をプレビューできます。

注意

段階的な変更のプレビューは、Microsoft の従業員のみが利用できます。

Microsoft の従業員: 投稿が "main" ブランチにマージされた後、https://review.learn.microsoft.com/windows/mixed-reality/enthusiast-guide?branch=main で公開される前にコンテンツを確認できます。 左側の列の目次を使用して、自分の記事を探します。

ブラウザーでの編集とデスクトップ クライアントを使用した編集

簡易変更を行うには、ブラウザーでの編集が最も簡単な方法です。ただし、いくつかの欠点があります。

  • スペルチェックは行われません。
  • 他の記事へのスマートリンクは表示されません (記事のファイル名を手動で入力する必要があります)。
  • イメージをアップロードして参照するのは面倒な場合があります。

これらの問題に対処したくない場合は、投稿するときに、いくつかの便利な拡張機能を持つ Visual Studio Code のようなデスクトップ クライアントを使用します。

Visual Studio Code の使用

上記の理由から、Web ブラウザーではなくデスクトップ クライアントを使用してドキュメントを編集することをお勧めします。 Visual Studio Code を使用することをお勧めします。

セットアップ

このリポジトリを使用するように Visual Studio Code を構成するには、こちらの手順に従います。

  1. Web ブラウザーで
    1. PC に Git をインストールします。
    2. Visual Studio Code をインストールします。
    3. まだ行っていない場合は、MicrosoftDocs/mixed-reality をフォークします。
    4. フォークで、[Clone or download](複製またはダウンロード) を選択し、URL をコピーします。
  2. Visual Studio Code でフォークのローカル複製を作成します。
    1. [View](表示) メニューで [Command Palette](コマンド パレット) を選択します。
    2. 「Git: Clone」と入力します。
    3. コピーした URL を貼り付けます。
    4. PC で複製を保存する場所を選択します。
    5. ポップアップで [Open repo](リポジトリを開く) を選択します。

ドキュメントの編集

次のワークフローを使用して、Visual Studio Code でドキュメントに変更を加えます。

注意

Visual Studio Code を使用する場合は、上記の、記事の編集と作成に関するすべてのガイダンスと Markdown の編集の基礎が適用されます。

  1. 複製されたフォークが公式リポジトリで最新の状態であることを確認します。

    1. Web ブラウザーで、MicrosoftDocs/Mixed-Reality "main" の他の寄稿者からの最近の変更をフォークに同期する pull request を作成します (矢印が正しい方法を指していることを確認してください)。

      MicrosoftDocs/Mixed-Reality からの変更をフォークに同期する

    2. Visual Studio Code で、同期ボタンを選択して、新しく更新されたフォークをローカル複製に同期します。

      同期ボタンの画像をクリックする

  2. Visual Studio Code を使用して、複製されたリポジトリで記事を作成または編集します。

    1. 1 つ以上の記事を編集します (必要に応じて、イメージを "images" フォルダーに追加します)。

    2. [Explorer] で変更を保存します。

      Explorer で

    3. [Source Control] で、[Commit All]\(すべてコミット)をクリックしてすべての変更をコミットします (プロンプトが出たらコミット メッセージを書き込みます)。

      Source Control で

    4. [sync](同期) ボタンを選択して、変更内容を元 (GitHub のフォーク) に同期します。

      同期ボタンをクリックする

  3. Web ブラウザーで Pull Request を作成して、フォークの新しい変更を MicrosoftDocs/mixed-reality の "main" に同期します (矢印が正しい方向を指していることを確認してください)。

    フォークから MicrosoftDocs/Mixed-Reality への pull request を作成する

便利な拡張機能

ドキュメントを編集する際には、次の Visual Studio Code 拡張機能が役立ちます。

  • Visual Studio Code 向けの Docs Markdown 拡張機能 - Alt + M を使用して、次のような docs 作成オプションのメニューを表示します。
    • アップロードしたイメージを検索して参照する。
    • リスト、テーブル、ドキュメント固有の呼び出しなどの書式設定 (>[!NOTE] など) を追加 する。
    • 内部リンクとブックマーク (ページ内の特定のセクションへのリンク) を検索して参照する。
    • 書式設定エラーを強調表示する (エラーの上にマウス ポインターを置くと詳細が表示される)。
  • Code Spell Checker - スペルミスの単語に下線が引かれます。スペルミスの単語を右クリックして変更するか、辞書に保存します。

issue を使用して Windows Mixed Reality 技術者向けガイドに関するフィードバックを提供する

フィードバックを提供したり、問題を指摘したりするには、実際のドキュメント ページを直接変更するのではなく、issue の作成を行います。コンテンツの所有者は、問題を適切なタイミングで解決できるように最善を尽くします。

特定のページに関する issue を作成する場合は、トピック タイトルと URL を必ず含めてください。

このコンテンツをサポートしていただき、ありがとうございます。