Windows Mixed Reality 開発者向けドキュメントへの貢献Contributing to Windows Mixed Reality developer documentation

Windows Mixed Reality 開発者向けドキュメントの公開リポジトリへようこそ。Welcome to the public repo for Windows Mixed Reality developer documentation! このリポジトリで作成または編集した記事 は、パブリックに表示されます。Any articles you create or edit in this repo will be visible to the public.

Windows Mixed Reality ドキュメントは現在、docs.microsoft.com プラットフォームにあります。このプラットフォームでは、flavored Markdown (Markdig 機能) が使用されています。Windows Mixed Reality docs are now on the docs.microsoft.com platform, which uses GitHub-flavored Markdown (with Markdig features). 基本的に、このリポジトリで編集するコンテンツは、に表示される書式設定されたページになり https://docs.microsoft.com/windows/mixed-reality ます。Essentially, the content you edit in this repo gets turned into formatted and stylized pages that show up at https://docs.microsoft.com/windows/mixed-reality.

このページでは、貢献するための基本的な手順とガイドライン、および Markdown の基礎へのリンクについて説明します。This page covers the basic steps and guidelines for contributing, as well as links to Markdown basics. 投稿いただき、ありがとうございます。Thank you for your contribution!

開始する前にBefore you start

まだお持ちでない場合は、 GitHub アカウントを作成する必要があります。If you don't already have one, you'll need to create a GitHub account.

注意

Microsoft の従業員の場合は、microsoft オープンソースポータルで GitHub アカウントを microsoft エイリアスにリンクします。If you're a Microsoft employee, link your GitHub account to your Microsoft alias on the Microsoft Open Source portal. "Microsoft" と "microsoft docs" の組織に参加してください。Join the "Microsoft" and "MicrosoftDocs" organizations).

GitHub アカウントを設定するときは、次のセキュリティに関する注意事項もお勧めします。When setting up your GitHub account, we also recommend these security precautions:

発行システムは GitHub に関連付けられており、GitHub エイリアスを使用して各記事の作成者または共同作成者として一覧表示されるため、これらの手順を実行することが重要です。Taking these steps is important, as the publishing system is tied to GitHub and you'll be listed as either author or contributor to each article using your GitHub alias.

既存の記事の編集Editing an existing article

次のワークフローを使用して、web ブラウザーで GitHub 経由で 既存の記事 の更新を行います。Use the following workflow to make updates to an existing article via GitHub in a web browser:

  1. "Mixed-reality" フォルダーで、編集する記事に移動します。Navigate to the article you wish to edit in the "mixed-reality-docs" folder.

  2. 右上にある [編集] ボタン (鉛筆アイコン) を選択します。Select the edit button (pencil icon) in the top right. これにより、破棄可能なブランチが自動的に ' master ' ブランチからフォークされます。This will automatically fork a disposable branch off the 'master' branch.

    記事を編集します。

  3. 記事の内容を編集します (ガイダンスについては、以下の 「Markdown の基礎」 を参照してください)。Edit the content of the article (see "Markdown basics" below for guidance).

  4. 各記事の上部にある該当するメタデータを更新します。Update metadata as relevant at the top of each article:

    • title: これは、記事が表示されているときに [ブラウザー] タブに表示されるページタイトルです。title: This is the page title that appears in the browser tab when the article is being viewed. これは SEO とインデックス作成に使用されるため、必要な場合を除き、タイトルを変更することはできません (ただし、ドキュメントが公開される前には重要度が低くなります)。As this is used for SEO and indexing, you shouldn't change the title unless necessary (though this is less critical before documentation goes public).
    • 説明: 記事の内容の簡単な説明を記述します。description: Write a brief description of the article's content. これは、SEO と検出に役立ちます。This aids in SEO and discovery.
    • author: ページのプライマリ所有者である場合は、ここに GitHub エイリアスを追加します。author: If you are the primary owner of the page, add your GitHub alias here.
    • ms. author: ページのプライマリ所有者である場合は、ここに Microsoft エイリアスを追加します (必要なのはエイリアスではありません @microsoft.com )。ms.author: If you are the primary owner of the page, add your Microsoft alias here (you don't need @microsoft.com, just the alias).
    • ms. date: ページに主要なコンテンツを追加する場合は日付を更新します。ただし、明確、書式設定、文法、スペルなどの修正には使用しません。ms.date: Update the date if you're adding major content to the page, but not for fixes like clarification, formatting, grammar, or spelling.
    • キーワード: キーワードは、SEO (検索エンジンの最適化) に役立ちます。keywords: Keywords aid in SEO (search engine optimization). コンマとスペースで区切られたキーワードを追加します。これは、記事に固有のものです (リスト内の最後のキーワードの後に区切り記号はありません)。すべての記事に適用するグローバルキーワードを追加する必要はありません。他の場所で管理されているためです。Add keywords, separated by a comma and a space, that are specific to your article (but no punctuation after the last keyword in your list); you don't need to add global keywords that apply to all articles, as those are managed elsewhere.
  5. 記事の編集が完了したら、下にスクロールして [ ファイル変更の提案 ] ボタンをクリックします。When you've completed your article edits, scroll down and click the Propose file change button.

  6. 次のページで、[ プル要求の作成 ] をクリックして、自動的に作成されたブランチを "マスター" にマージします。On the next page, click Create pull request to merge your automatically-created branch into 'master.'

  7. 編集する次の記事に対して上記の手順を繰り返します。Repeat the steps above for the next article you want to edit.

既存のアーティクルの名前の変更または削除Renaming or deleting an existing article

既存のアーティクルの名前を変更または削除する場合は、必ずリダイレクトを追加してください。If your change will rename or delete an existing article, be sure to add a redirect. こうすることで、既存の記事へのリンクを持つユーザーは、引き続き適切な場所に配置されます。That way, anyone with a link to the existing article will still end up in the right place. リダイレクトは、リポジトリのルートにあるファイルの .openpublishing.redirection.jsによって管理されます。Redirects are managed by the .openpublishing.redirection.json file in the root of the repo.

.openpublishing.redirection.jsにリダイレクトを追加するには、次のように、配列にエントリを追加し redirections ます。To add a redirect to .openpublishing.redirection.json, add an entry to the redirections array:

{
    "redirections": [
        {
            "source_path": "mixed-reality-docs/old-article.md",
            "redirect_url": "new-article#section-about-old-topic",
            "redirect_document_id": false
        },
  • source_pathは、削除しようとしている古いアーティクルへの相対リポジトリパスです。The source_path is the relative repository path to the old article that you're removing. パスがで始まり、で終わることを確認してください mixed-reality-docs .mdBe sure the path starts with mixed-reality-docs and ends with .md.
  • は、 redirect_url 以前の記事から新しい記事までの相対パブリック URL です。The redirect_url is the relative public URL from the old article to the new article. この URL は、 does not mixed-reality-docs .md リポジトリパスではなくパブリック url を参照しているため、またはを含んでいないことを確認してください。Be sure that this URL does not contain mixed-reality-docs or .md, as it refers to the public URL and not the repository path. を使用した新しいアーティクル内のセクションへのリンク #section は許可されます。Linking to a section within the new article using #section is allowed. 必要に応じて、ここで別のサイトへの絶対パスを使用することもできます。You may also use an absolute path to another site here, if necessary.
  • redirect_document_id 前のファイルのドキュメント ID を保持するかどうかを示します。redirect_document_id indicates whether you would like to keep the document ID from the previous file. 既定値は、false です。The default is false. リダイレクトされたアーティクルの属性値を保持する場合は、を使用し true ms.documentid ます。Use true if you want to preserve the ms.documentid attribute value from the redirected article. ドキュメント ID を保持している場合は、ページビューやランキングなどのデータがターゲットアーティクルに転送されます。If you preserve the document ID, data, such as page views and rankings, will be transferred to the target article. これは、リダイレクトが主に名前の変更であり、同じコンテンツの一部のみをカバーする別の記事へのポインターではない場合に実行します。Do this if the redirect is primarily a rename, and not a pointer to different article that only covers some of the same content.

リダイレクトを追加する場合は、古いファイルも必ず削除してください。If you add a redirect, be sure to delete the old file as well.

新しい記事を作成していますCreating a new article

次のワークフローを使用して、web ブラウザーで GitHub を使用してドキュメントリポジトリに 新しい記事を作成 します。Use the following workflow to create new articles in the documentation repo via GitHub in a web browser:

  1. Microsoft Docs/mixed reality の "マスター" ブランチからフォークを作成します (右上の [ フォーク ] ボタンを使用します)。Create a fork off the MicrosoftDocs/mixed-reality 'master' branch (using the Fork button in the top right).

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

  2. "Mixed-reality" フォルダーで、右上にある [ 新しいファイルの作成 ] ボタンをクリックします。In the "mixed-reality-docs" folder, click the Create new file button in the top right.

  3. アーティクルのページ名を作成します (スペースの代わりにハイフンを使用し、句読点やアポストロフィは使用しません)。 "md" を追加します。Create a page name for the article (use hyphens instead of spaces and don't use punctuation or apostrophes) and append ".md"

    新しいページの名前を指定します。

    重要

    必ず、"mixed-docs" フォルダー内から新しい記事を作成してください。Make sure you create the new article from within the "mixed-reality-docs" folder. これを確認するには、新しいファイル名の行で "/mixed-reality-docs/" を確認します。You can confirm this by checking for "/mixed-reality-docs/" in the new file name line.

  4. 新しいページの上部に、次のメタデータブロックを追加します。At the top of your new page, add the following metadata block:

    ---
    title:
    description:
    author:
    ms.author:
    ms.date:
    ms.topic: article
    keywords:
    ---
    
  5. 上記のセクションの手順に従って、関連するメタデータフィールドを入力します。Fill in the relevant metadata fields per the instructions in the section above.

  6. Markdown の基礎を使用して、記事の内容を記述します。Write article content using Markdown basics.

  7. ## See also記事の下部に、関連するその他の記事へのリンクが記載されたセクションを追加します。Add a ## See also section at the bottom of the article with links to other relevant articles.

  8. 完了したら、[ 新しいファイルのコミット ] をクリックします。When finished, click Commit new file .

  9. [ 新しいプル要求 ] をクリックし、フォークの ' master ' ブランチを microsoft docs/mixed reality ' マスター ' にマージします (矢印が正しい方法を指していることを確認してください)。Click New pull request and merge your fork's 'master' branch into MicrosoftDocs/mixed-reality 'master' (make sure the arrow is pointing the correct way).

    フォークからのプル要求を作成して、Microsoft Docs/mixed reality に

Markdown の基本Markdown basics

Markdown 言語を使用してドキュメントを編集する方法については、次のリソースを参照してください。The following resources will help you learn how to edit documentation using the Markdown language:

テーブルの追加Adding tables

Docs.microsoft.com スタイルの表では、インライン CSS を試す場合でも、罫線やカスタムスタイルはありません。Because of the way docs.microsoft.com styles tables, they won’t have borders or custom styles, even if you try inline CSS. これは短時間は機能しているように見えますが、最終的には、プラットフォームによってテーブルからスタイルが除去されます。It will appear to work for a short period of time, but eventually the platform will strip the styling out of the table. そのため、事前に計画し、テーブルを単純にしておきます。So plan ahead and keep your tables simple. Markdown テーブルを簡単に作成できるサイトは次のようになります。Here’s a site that makes Markdown tables easy.

Visual Studio Code の Docs Markdown 拡張機能では、 Visual Studio Code (下記参照)を使用してドキュメントを編集する場合にも、テーブルの生成を簡単に行うことができます。The Docs Markdown Extension for Visual Studio Code also makes table generation easy if you're using Visual Studio Code (see below) to edit the documentation.

追加 (イメージを)Adding images

リポジトリの "mixed-reality/images" フォルダーにイメージをアップロードし、記事で適切に参照する必要があります。You’ll need to upload your images to the "mixed-reality-docs/images" folder in the repo, and then reference them appropriately in the article. 画像は自動的にフルサイズで表示されます。つまり、画像が大きい場合は、記事全体の幅がいっぱいになります。Images will automatically show up at full-size, which means if your image is large, it’ll fill the entire width of the article. したがって、アップロードする前にイメージのサイズを事前に設定することをお勧めします。Thus, we recommend pre-sizing your images before uploading them. 推奨される幅は、600 ~ 700 ピクセルです。ただし、サイズの細かいスクリーンショットやスクリーンショットの一部である場合は、サイズを変更する必要があります。The recommended width is between 600 and 700 pixels, though you should size up or down if it’s a dense screenshot or a fraction of a screenshot, respectively.

重要

マージする前に、フォークされたリポジトリにのみイメージをアップロードできます。You can only upload images to your forked repo before merging. そのため、記事にイメージを追加する予定がある場合は、まず、 Visual Studio Code を使用 して、最初にそのイメージをフォークの "images" フォルダーに追加するか、web ブラウザーで次の操作を行っていることを確認する必要があります。So, if you plan on adding images to an article, you'll need to use Visual Studio Code to add the images to your fork's "images" folder first or make sure you've done the following in a web browser:

  1. Microsoft Docs/mixed reality リポジトリをフォークしています。Forked the MicrosoftDocs/mixed-reality repo.
  2. フォーク内のアーティクルを編集しています。Edited the article in your fork.
  3. 記事で参照しているイメージを、フォーク内の "mixed-reality/images" フォルダーにアップロードしました。Uploaded the images you're referencing in your article to the "mixed-reality-docs/images" folder in your fork.
  4. フォークを Microsoft Docs/mixed reality の ' master ' ブランチにマージする プル要求 を作成しました。Created a pull request to merge your fork into the MicrosoftDocs/mixed-reality 'master' branch.

独自にフォークしたリポジトリを設定する方法については、 新しい記事を作成するための手順に従ってください。To learn how to set up your own forked repo, follow the instructions for creating a new article.

作業のプレビューPreviewing your work

Web ブラウザーを使用して GitHub で編集しているときに、ページの上部にある [ プレビュー ] タブをクリックして、コミットする前に作業内容をプレビューすることができます。While editing in GitHub via a web browser, you can click the Preview tab near the top of the page to preview your work before committing.

注意

review.docs.microsoft.com での変更のプレビューは、Microsoft の従業員のみが利用できます。Previewing your changes on review.docs.microsoft.com is only available to Microsoft employees

Microsoft の従業員: 投稿物が "master" ブランチにマージされると、ドキュメントが公開される前にどのように表示されるかを確認でき https://review.docs.microsoft.com/windows/mixed-reality?branch=master ます (左側の列の目次を使用して記事を検索します)。Microsoft employees: once your contributions have been merged into the 'master' branch, you can see what the documentation will look like before it goes public at https://review.docs.microsoft.com/windows/mixed-reality?branch=master (find your article using the table of contents in the left column).

ブラウザーでの編集とデスクトップクライアントを使用した編集Editing in the browser vs. editing with a desktop client

クイック変更を行うには、ブラウザーでの編集が最も簡単な方法です。ただし、いくつかの欠点があります。Editing in the browser is the easiest way to make quick changes, however, there are a few disadvantages:

  • スペルチェックは行われません。You don't get spell-check.
  • 他の記事へのスマートリンクは表示されません (記事のファイル名を手動で入力する必要があります)。You don't get any smart-linking to other articles (you have to manually type the article's filename).
  • イメージをアップロードして参照するのは面倒な場合があります。It can be a hassle to upload and reference images.

これらの問題に対処しない場合は、 Visual Studio Code のようなデスクトップクライアントを使用して、ドキュメントに寄与する 便利な拡張機能 をいくつか使用することをお勧めします。If you'd rather not deal with these issues, you may prefer to use a desktop client like Visual Studio Code with a couple helpful extensions to contribute to documentation.

Visual Studio Code の使用Using Visual Studio Code

上記の理由から、デスクトップクライアントを使用して、web ブラウザーではなくドキュメントを編集することをお勧めします。For the reasons listed above, you may prefer using a desktop client to edit documentation instead of a web browser. Visual Studio Codeを使用することをお勧めします。We recommend using Visual Studio Code.

セットアップSetup

このリポジトリを使用するように Visual Studio Code を構成するには、次の手順に従います。Follow these steps to configure Visual Studio Code to work with this repo:

  1. Web ブラウザーで次のようにします。In a web browser:
    1. PC の Git をインストールします。Install Git for your PC.
    2. Visual Studio Code をインストールします。Install Visual Studio Code.
    3. まだお持ちでない場合は、 Microsoft docs/mixed reality をフォークします。Fork MicrosoftDocs/mixed-reality if you haven't already.
    4. フォークで、[ 複製] または [ダウンロード ] をクリックし、URL をコピーします。In your fork, click Clone or download and copy the URL.
  2. Visual Studio Code でフォークのローカル複製を作成します。Create a local clone of your fork in Visual Studio Code:
    1. [ 表示 ] メニューの [ コマンドパレット ] をクリックします。From the View menu, select Command Palette .
    2. 「Git: Clone」と入力します。Type "Git:Clone."
    3. コピーしたばかりの URL を貼り付けます。Paste the URL you just copied.
    4. コンピューターの複製を保存する場所を選択します。Choose where to save the clone on your PC.
    5. ポップアップ画面で [ リポジトリを開く ] をクリックします。Click Open repo in the pop-up.

ドキュメントの編集Editing documentation

次のワークフローを使用して、Visual Studio Code でドキュメントに変更を加えます。Use the following workflow to make changes to the documentation with Visual Studio Code:

注意

Visual Studio Code を使用する場合は、記事の 編集作成 に関するすべてのガイダンスと、上記の Markdown の編集の基礎が適用されます。All the guidance for editing and creating articles, and the basics of editing Markdown, from above applies when using Visual Studio Code as well.

  1. 複製されたフォークが公式リポジトリを使用して最新の状態になっていることを確認します。Make sure your cloned fork is up-to-date with the official repo.

    1. Web ブラウザーでプル要求を作成して、Microsoft Docs/mixed reality ' master ' の他の共同作成者からの最近の変更をフォークに同期します (矢印が正しい方法であることを確認してください)。In a web browser, create a pull request to sync recent changes from other contributors in MicrosoftDocs/mixed-reality 'master' to your fork (make sure the arrow is pointing the right way).

      Microsoft Docs/mixed-reality からフォークへの変更の同期

    2. Visual Studio Code で、[同期] ボタンをクリックして、新しく更新したフォークをローカルクローンに同期します。In Visual Studio Code, click the sync button to sync your freshly updated fork to the local clone.

      [同期] ボタンの画像をクリックします。

  2. Visual Studio Code を使用して、複製されたリポジトリのアーティクルを作成または編集します。Create or edit articles in your cloned repo using Visual Studio Code.

    1. 1つ以上の記事を編集します (必要に応じて、画像を "images" フォルダーに追加します)。Edit one or more articles (add images to “images” folder if necessary).

    2. 変更を エクスプローラー保存 します。Save changes in Explorer .

      エクスプローラーで [すべてを保存] を選択します。

    3. ソース管理 ですべての変更を コミット します (メッセージが表示されたら書き込みコミットメッセージ)。Commit all changes in Source Control (write commit message when prompted).

      ソース管理で [すべてコミット] を選択する

    4. [ 同期 ] ボタンをクリックして、変更内容を元に戻します (GitHub のフォーク)。Click the sync button to sync your changes back to origin (your fork on GitHub).

      [同期] ボタンをクリックします。

  3. Web ブラウザーでプル要求を作成して、フォークの新しい変更を Microsoft Docs/mixed reality ' マスター ' に戻します (矢印が正しい方法であることを確認してください)。In a web browser, create a pull request to sync new changes in your fork back to MicrosoftDocs/mixed-reality 'master' (make sure the arrow is pointing the correct way).

    フォークからのプル要求を作成して、Microsoft Docs/mixed reality に

便利な拡張機能Useful extensions

ドキュメントを編集する際には、次の Visual Studio Code 拡張機能が非常に役立ちます。The following Visual Studio Code extensions are very useful when editing documentation:

  • Docs Markdown Extension for Visual Studio Code - Alt + M キー を使用して、次のような docs 作成オプションのメニューを表示します。Docs Markdown Extension for Visual Studio Code - Use Alt+M to bring up a menu of docs authoring options like:
    • アップロードしたイメージを検索して参照します。Search and reference images you've uploaded.
    • など、リスト、テーブル、ドキュメント固有の呼び出しなどの書式設定を追加 >[!NOTE] します。Add formatting like lists, tables, and docs-specific call-outs like >[!NOTE].
    • 内部リンクとブックマーク (ページ内の特定のセクションへのリンク) を検索して参照します。Search and reference internal links and bookmarks (links to specific sections within a page).
    • 書式設定エラーが強調表示されます (詳細については、エラーの上にマウスポインターを置きます)。Formatting errors are highlighted (hover your mouse over the error to learn more).
  • コードスペルチェッカー -スペルミスの単語に下線が引かれます。スペルミスの単語を右クリックして変更するか、辞書に保存します。Code Spell Checker - misspelled words will be underlined; right-click on a misspelled word to change it or save it to the dictionary.