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 ドキュメントは、GitHub flavored Markdown (Markdig 機能) を使用して、docs.microsoft.com プラットフォームではようになりました。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

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

注意

Microsoft 従業員の場合は、GitHub アカウントに、Microsoft エイリアスをリンクをMicrosoft のオープン ソース ポータルします。If you're a Microsoft employee, link your GitHub account to your Microsoft alias on the Microsoft Open Source portal. 結合、 "Microsoft""MicrosoftDocs" 組織)。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. "混合-実際には、docs"フォルダーで編集する記事に移動します。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. 破棄可能な分岐 'マスター' ブランチをオフにこれは自動的に分岐します。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: 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:記事の内容の簡単な説明を記述します。description: Write a brief description of the article's content. SEO と検出を容易にします。This aids in SEO and discovery.
    • 作成者:ページのプライマリ所有者の場合は、ここで、GitHub のエイリアスを追加します。author: If you are the primary owner of the page, add your GitHub alias here.
    • ms.author:ページのプライマリ所有者の場合は、追加のエイリアスは、ここ、マイクロソフト (する必要はありません@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.

新しいアーティクルの作成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. MicrosoftDocs/複合現実 'マスター' ブランチをフォークを作成 (を使用して、フォーク右上のボタン)。Create a fork off the MicrosoftDocs/mixed-reality 'master' branch (using the Fork button in the top right).

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

  2. "混合-実際には、docs"フォルダーで、をクリックして、新しいファイルの作成右上のボタンをクリックします。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"

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

    重要

    "混合-実際には、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. クリックして新しいプル要求MicrosoftDocs/複合現実 'master' にフォークの 'マスター' ブランチをマージし、(矢印が正しい方法を指していることを確認してください)。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).

    MicrosoftDocs/複合現実に自分のフォークからプル要求を作成する.

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 Extensionによりを使用する場合に簡単に生成をどのようにテーブルも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

リポジトリで"混在-実際には、docs/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. MicrosoftDocs/複合現実のリポジトリをフォークします。Forked the MicrosoftDocs/mixed-reality repo.
  2. フォーク内の記事を編集します。Edited the article in your fork.
  3. フォークに"混在-実際には、docs/images"フォルダーに、記事を参照しているイメージをアップロードします。Uploaded the images you're referencing in your article to the "mixed-reality-docs/images" folder in your fork.
  4. 作成、プル要求MicrosoftDocs/複合現実 'マスター' ブランチに独自のフォークをマージします。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 の従業員: お客様の投稿物は、'マスター' ブランチにマージされましたが後のドキュメントの外観に公表前に参照してくださいできます 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. フォーク MicrosoftDocs/複合現実まだ行っていない場合。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. PC のクローンを保存する場所を選択します。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:

注意

すべてのガイダンス編集作成記事、およびMarkdown を編集の基本、上からも、Visual Studio Code を使用するときに適用されます。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 ブラウザーで独自のフォークに MicrosoftDocs/複合現実 '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).

      独自のフォークに MicrosoftDocs/複合現実から変更の同期

    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. (追加イメージ"の images"フォルダーに必要な場合)、1 つまたは複数の記事を編集します。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 ブラウザーで新しいフォーク MicrosoftDocs/複合現実 'master' に変更を同期するプル要求の作成 (矢印が正しい方法を指していることを確認してください)。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).

    MicrosoftDocs/複合現実に自分のフォークからプル要求を作成する.

有用な拡張機能Useful extensions

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

  • Visual Studio Code 用 docs Markdown Extension -使用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.
    • テーブルを一覧表示などの書式設定となどの docs 固有の注意を追加>[!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.