Mixed Reality 開発者向けドキュメントへの投稿

  • [アーティクル]

Mixed Reality 開発者向けドキュメントのパブリック リポジトリへようこそ。 このリポジトリで作成または編集した記事は、一般公開されます。

Mixed Realityドキュメントは、GitHub フレーバーの Markdown と Markdig 機能を使用する Microsoft Learn でホストされるようになりました。 このリポジトリで編集したコンテンツは、 に表示 /windows/mixed-realityされるスタイル設定されたページに書式設定されます。

このページでは、投稿の基本的な手順とガイドライン、および Markdown の基本へのリンクを取り扱います。 投稿いただき、ありがとうございます。

使用可能なリポジトリ

リポジトリ名です URL
Azure Object Anchors MicrosoftDocs/azure-docs/articles/object-anchors
Azure Remote Rendering MicrosoftDocs/azure-docs/articles/remote-rendering
Azure Spatial Anchors MicrosoftDocs/azure-docs/articles/spatial-anchors
HoloLens MicrosoftDocs/HoloLens
Mixed Reality MicrosoftDocs/mixed-reality
VR 愛好者向けガイド MicrosoftDocs/mixed-reality/enthusiast-guide

開始する前に

まだお持ちでない場合は、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 エイリアスを使用して、各記事の作成者または共同作成者として記載されます。

既存の記事の編集

次のワークフローを使用して、Webブラウザーで GitHub を介して "既存の記事" を更新します。

  1. "mixed-reality-docs" フォルダーで編集する記事に移動します。

  2. 右上にある [編集] ボタン (鉛筆アイコン) を選択します。これにより、"マスター" ブランチから、破棄可能なブランチが自動的にフォークされます。

    記事を編集します。

  3. "Markdown の基礎" に従って、記事の内容を編集します。

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

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

  5. 記事の編集が完了したら、下にスクロールして [Propose file change](ファイル変更の提案) を選択します。

  6. 次のページで、[Pull Request を作成] を選択し、自動的に作成されたブランチを "マスター" にマージします。

  7. 次に編集する記事について、上記の手順を繰り返します。

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

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

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

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

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

新しい記事の作成

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

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

    フォークの作成。

  2. "mixed-reality-docs" フォルダーで、右上にある [新しいファイルの作成] を選択します。

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

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

    重要

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

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

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

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

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

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

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

  9. [新しい Pull Request] を選択し、フォークの "マスター" ブランチを MicrosoftDocs/mixed-reality の "マスター" にマージします (矢印が正しい方向を指していることを確認してください)。

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

Markdown の基本

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

テーブルの追加

Microsoft のテクニカル ドキュメント スタイル テーブルの方法により、インライン 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 の "マスター" ブランチにマージする Pull Request を作成した。

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

作業のプレビュー

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

注意

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

Microsoft の従業員: 投稿が 'main' ブランチにマージされたら、/windows/mixed-reality?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 "マスター" の他の寄稿者からの最近の変更をフォークに同期する 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 の "マスター" に同期します (矢印が正しい方向を指していることを確認してください)。

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

便利な拡張機能

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

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