ドキュメント ガイドライン — MRTK2

このドキュメントでは、Mixed Reality Toolkit (MRTK) のドキュメントガイドラインと標準について説明します。 ここでは、ドキュメントの作成と生成の技術的な側面を紹介し、一般的な落とし穴を強調し、推奨される記述スタイルについて説明します。

このページ自体が 1 つの例になるようにするために、ここではドキュメントの目的のスタイルと最も一般的なマークアップ機能を使用します。

• ソース
• 使用方法
• 設計
• パフォーマンス上の注意点
• 重大な変更

---

機能とマークアップ

このセクションでは、頻繁に必要となる機能について説明します。 それらの動作を確認するには、ページのソース コードを参照してください。

1. 番号付きリスト
   1. 先頭に空白が少なくとも 3 つ含まれている入れ子になった番号付きリスト
   2. コード内の実際の番号は関係ありません。解析によって、正しい項目番号の設定が行われます。

• 箇条書きリスト
  • 入れ子になった箇条書きリスト
• 太字のテキストは **二重アスタリスク** を使用
• 斜体のテキストは _アンダースコア_ または *一重アスタリスク* を使用
• highlighted as code のテキストは `バッククォート` を使用
• ドキュメント ページ MRTK ドキュメントのガイドラインへのリンク
• ページ内のアンカーへのリンク。アンカーは、スペースをダッシュに置き換え、小文字に変換することによって形成されます

コード サンプルでは、3 つのバックチック ``` を持つブロックを使用し、構文の強調表示の言語として csharp を指定します。

int SampleFunction(int i)
{
   return i + 42;
}

文内のコードに言及する場合、use a single backtick。

TODO

ドキュメントでは TODO を使用しないようにしてください。時間が経つうちに、これらの TODO (コード TODO など) が蓄積され、更新方法とその理由に関する情報が失われる傾向があるためです。

TODO を追加する必要がある場合は、次の手順に従います。

1. TODO の背後にあるコンテキストを説明する新しい問題を Github に投稿し、別の共同作成者が TODO を理解して対処できる十分な背景を提供します。
2. ドキュメントの TODO で問題の URL を示します。

<!-- TODOhttps://github.com/microsoft/MixedRealityToolkit-Unity/issues/ISSUE_NUMBER_HERE: 問題に関する簡単な宣伝文 -->

強調表示されたセクション

閲覧者の特定のポイントを強調表示するには、[ > !注] 、 > [!WARNING] 、 、および > [![重要] をクリックすると、次のスタイルが生成されます。 一般的なポイントについては「注意」を使用することが推奨され、特に関連のあるケースについては「警告」または「重要」で指摘します。

Note

注意の例

警告

警告の例

重要

重要なコメントの例

ページのレイアウト

はじめに

章のメイン タイトルの直後の部分は、章の概要を示す短い紹介として使う必要があります。 長くしすぎず、代わりに小見出しを追加します。 これらを使用すると、セクションにリンクでき、ブックマークとして保存できます。

メインの本文

残りの部分を構造化するために、レベル 2 とレベル 3 の見出しを使用します。

ミニ セクション

目立つ必要があるブロックには、太字のテキスト行を使用します。これは、ある時点でレベル 4 の見出しに置き換える可能性があります。

「関連項目」セクション

ほとんどのページは、"関連項目" と呼ばれる章で終わる必要があります。 この章は、このトピックに関連するページへのリンクの箇条書きリストです。 これらのリンクは、必要に応じてページ テキスト内に表示される場合がありますが、これは必須ではありません。 同様に、ページ テキストには、メイン トピックに関連付けられていないページへのリンクが含まれている場合もあり、これらは "関連項目" の一覧に含めないでください。 リンクの選択の例として、このページの"関連項目" も参照してください。

目次 (TOC)

TOC ファイルは、MRTK github.io ドキュメントのナビゲーション バーを生成するために使用されます。 新しいドキュメント ファイルが追加されるたびに、そのファイルのエントリが documentation フォルダーのいずれかの toc.yml ファイルに含められていることを確認してください。 TOC ファイルに一覧表示されている記事だけが、開発者ドキュメントのナビゲーションに表示されます。documentation フォルダー内のすべてのサブフォルダーに対して TOC ファイルを作成し、既存の TOC ファイルにリンクして、ナビゲーションの対応する部分にサブセクションとして追加できます。

スタイル

記述スタイル

一般的な規則概要: プロフェッショナルな語調に徹します。 これは通常、「会話のトーン」を避けることを意味します。 また、誇張や扇情的な言い回しを避けます。

1. ふざけすぎないようにします。
2. 自分を主語にしません。
3. 「私達」を使いません。 これは通常、'MRTK' を使用して簡単に言い換えられます。 例: 「私達はこの機能をサポートします」と書く代わりに、「MRTK はこの機能をサポートしています」または「次の機能がサポートされています」とします。
4. 同様に、「あなた」を使用しないようにします。 例: 「この単純な変更により、あなたのシェーダーは構成可能になります」の代わりに「少しの労力で、シェーダーを構成可能にできます」とします。
5. 冗長な言い回しを使用しないようにします。
6. 過剰に刺激的に聞こえないようにします。私達は何も販売する必要はありません。
7. 同様に、大げさ過ぎないようにします。 感嘆符を使用する必要はほぼありません。

[大文字/小文字の設定]

• 見出しに見出し文を使用します。つまり、文頭の文字と名前を大文字にしますが、それ以外は何もしません。
• それ以外の場合は、通常の英語を使用します。 つまり、そのコンテキストで特別な意味を持っていても、任意の単語を大文字にしません。 特定の単語を強調表示するには、斜体のテキストを使用します。以下を参照してください。
• リンクが文に埋め込まれている場合 (推奨される方法)、標準の章名は常に大文字を使用するため、テキスト内で任意に大文字を使用しない規則を破っています。 そのため、この大文字の問題を修正するため、カスタム リンク名を使用します。 例: 境界コントロールのドキュメントへのリンクを次に示します。
• Unity などの名前は大文字にします。
• Unity editor と記述する場合、"editor" を大文字にしないでください。

強調と強調表示

単語を強調または強調表示するには、太字または斜体にするという 2 つの方法があります。 太字のテキストの効果として、太字のテキストは目立ち、そのために、テキストの一部をざっと見たり、ページをスクロールするだけでも、簡単に認識できたりすることがあります。 太字は、ユーザーが覚えておく必要があるフレーズを強調表示する場合に最適です。 ただし、一般には気が散るので、太字のテキストはあまり使用しないようにします。

多くの場合、論理的にひとまとまりになっているものを "グループ化" したり、特定の用語が特別な意味を持つためにこれを強調表示したりすることが必要になります。 このような場合は、テキスト全体を目立たせる必要はありません。 任意の項目を強調表示するための "簡易な方法" として、斜体のテキストを使用します。

同様に、テキスト内でファイル名、パス、またはメニュー エントリに言及する場合、これを斜体にすることで、読者の気が散らないように論理的にグループ化します。

一般論として、不要なテキストの強調表示を避けるようにしてください。 特別な用語は 1 回強調表示して、読者に気付かせます。その必要がなくなり、気が散るだけになったときに、テキスト全体でこのような強調表示を繰り返さないようにします。

メニュー エントリへの言及

ユーザーがクリックする必要のあるメニュー エントリを指定する場合、現在の規則は次のようになります。[プロジェクト]>[ファイル]>[作成]>[リーフ]

リンク

可能な限り多くの便利なリンクを他のページに挿入しますが、各リンクは 1 回だけ挿入します。 読者がページ内のすべてのリンクをクリックし、同じページが 20 回開いたら、それがどれだけ煩わしいか考えてみてください。

文に埋め込まれたリンクを優先します。

• 悪い例: ガイドラインは役に立ちます。 詳細については、この章を参照してください。
• 良い例: ガイドラインは役に立ちます。

外部リンクは避けます。これらは古くなったり、著作権で保護されたコンテンツが含まれたりする可能性があります。

リンクを追加するときに、「関連項目」セクションにも表示すべきかどうかを検討してください。 同様に、新しいページへのリンクをリンク先ページに追加するかどうかを確認します。

画像またはスクリーンショット

スクリーンショットは、控えめに使用します。 ドキュメント内の画像の管理は労力を必要とし、UI の小さな変更によって、多数のスクリーンショットが古くなる可能性があります。 次の規則により、メンテナンス作業が削減されます。

1. テキストで記述できる場合は、スクリーンショットを使用しないようにします。 特に、プロパティの名前と値を表示するための唯一の目的として、プロパティ グリッドのスクリーンショットを使用しないようにします。
2. スクリーンショットには、表示される情報に関係のないものを含めないようにする必要があります。 たとえば、レンダリング効果を示す場合、ビューポートのスクリーンショットを作成しますが、その周囲の UI は除外します。 一部の UI を表示し、その重要な部分だけが画像内に含まれるように、ウィンドウを移動してみてください。
3. スクリーンショット UI を含めた場合は、重要な部分のみを表示します。 たとえば、ツール バーのボタンについて説明する場合は、重要なツール バー ボタンを示す小さなイメージを作成しますが、その周りのすべてを除外します。
4. 再作成しやすい画像のみを使用します。 つまり、マーカーや強調表示をスクリーンショットに描画しません。 まず、これらがどのように表示されるのかについての一貫したルールはありません。 2 つ目は、このようなスクリーンショットを再作成するのは労力を要します。 代わりに、重要な部分をテキストで記述します。 このルールには例外がありますが、それらはまれです。
5. アニメーション GIF を再作成するのは、明らかにはるかに多くの労力を要します。 それを再作成する作業を永遠に担当しなければならない場合を想像してみてください。あるいは、その時間を費やしたくないと思った人は、その作業を止めてしまうことを予想してみてください。
6. 記事内の画像の数を少ない状態に保ちます。 多くの場合、何らかのツールのすべてを示す全体的なスクリーンショットを 1 つ作成し、残りをテキストで記述するのが良い方法です。 これにより、必要に応じてスクリーンショットを簡単に置き換えできます。

その他の側面は次のとおりです。

• スクリーン ショットのエディター UI では、淡い灰色のテーマ エディターを使用する必要があります。これは、すべてのユーザーがダーク テーマにアクセスできるわけではなく、また可能な限り一貫性を維持する必要があるためです。
• ほとんどのモニターに表示される既定の画像の幅は 500 ピクセルです。 これをあまり逸脱しないようにしてください。幅の最大値は 800 ピクセルである必要があります。
• UI のスクリーンショットには PNG を使用します。
• 3D ビューポートのスクリーンショットには、PNG または JPG を使用します。 圧縮率よりも品質を優先します。

コンポーネントのプロパティの一覧

プロパティの一覧を文書化する場合は、太字のテキストを使用してプロパティ名を強調表示し、改行と標準テキストを使用してそれらを説明します。 サブ章や箇条書きリストは使用しません。

また、すべての文末に句点を付けるようにしてください。

ページ完成のチェックリスト

1. このドキュメントのガイドラインに従っていることを確認します。
2. ドキュメント構造を参照し、他のページの「関連項目」セクションの下に新しいドキュメントが記述されているかどうかを確認します。
3. 可能な場合は、トピックの知識を持つ人に、技術的な正しさについてページを校正してもらいます。
4. 他の誰かに、スタイルと書式設定についてページを校正してもらいます。 この人は、このトピックに馴染みのない人でも構いません。ドキュメントがどれだけ理解できるかについてフィードバックをもらうのもよい方法です。

ソース ドキュメント

API ドキュメントは、MRTK ソース ファイルから自動的に生成されます。 これを容易にするために、ソース ファイルには次の情報が含まれている必要があります。

• クラス、構造体、列挙の概要ブロック
• プロパティ、メソッド、イベントの概要ブロック
• 機能の概要バージョンと依存関係
• シリアル化されたフィールド
• 列挙値

上記に加えて、メンテナンス、バグ修正、カスタマイズが簡単にできるようにするために、コードに十分なコメントを付ける必要があります。

クラス、構造体、列挙の概要ブロック

クラス、構造体、または列挙を MRTK に追加する場合は、その目的を記述する必要があります。 これは、クラスの上の概要ブロックの形式をとります。

/// <summary>
/// AudioOccluder implements IAudioInfluencer to provide an occlusion effect.
/// </summary>

クラス レベルの依存関係がある場合は、概要のすぐ下の注釈ブロックに文書化する必要があります。

/// <remarks>
/// Ensure that all sound emitting objects have an attached AudioInfluencerController.
/// Failing to do so will result in the desired effect not being applied to the sound.
/// </remarks>

クラス、構造体、または列挙の概要なしで送信されたプル要求は承認されません。

プロパティ、メソッド、イベントの概要ブロック

プロパティ、メソッド、イベント (PME) とフィールドは、コードの可視性 (パブリック、プライベート、保護、内部) に関係なく、概要ブロックで文書化されます。 ドキュメント生成ツールは、フィルター除外を行って、パブリックおよび保護された機能のみを発行する役割を担います。

注意: Unity メソッド (例: 起動、開始、更新) については、概要ブロックは必要ありません。

プル要求を承認するには、PME ドキュメントが必要です。

PME の概要ブロックの一部として、パラメーターと返されるデータの意味と目的が必要です。

/// <summary>
/// Sets the cached native cutoff frequency of the attached low pass filter.
/// </summary>
/// <param name="frequency">The new low pass filter cutoff frequency.</param>
/// <returns>The new cutoff frequency value.</returns>

機能の概要バージョンと依存関係

API の概要ドキュメントの一部として、機能が導入された MRTK バージョンに関する情報と、すべての依存関係を注釈ブロックに記載する必要があります。

依存関係には、拡張機能やプラットフォームの依存関係が含まれる必要があります。

/// <remarks>
/// Introduced in MRTK version: 2018.06.0
/// Minimum Unity version: 2018.0.0f1
/// Minimum Operating System: Windows 10.0.11111.0
/// Requires installation of: ImaginarySDK v2.1
/// </remarks>

シリアル化されたフィールド

Unity のツールヒント属性を使用して、インスペクター内のスクリプトのフィールドにランタイム ドキュメントを提供することをお勧めします。

構成オプションが API ドキュメントに含まれるようにするには、"少なくとも" 概要ブロックにツールヒントの内容を含めるスクリプトが必要です。

/// <summary>
/// The quality level of the simulated audio source (ex: AM radio).
/// </summary>
[Tooltip("The quality level of the simulated audio source.")]

列挙値

列挙を定義する場合、コードでも概要ブロックを使用して列挙値の意味を文書化する必要があります。 必要に応じて、注釈ブロックを使用して、理解を深めるために追加の詳細を提供できます。

/// <summary>
/// Full range of human hearing.
/// </summary>
/// <remarks>
/// The frequency range used is a bit wider than that of human
/// hearing. It closely resembles the range used for audio CDs.
/// </remarks>

使用方法に関するドキュメント

Mixed Reality Toolkit の多くのユーザーは、API ドキュメントを使用する必要がない場合があります。 これらのユーザーは、事前に作成された再利用可能なプレハブとスクリプトを利用して、エクスペリエンスを作成します。

各機能領域には、提供される内容をかなり高いレベルで記述する 1 つ以上のマークダウン (.md) ファイルが含まれます。 特定の機能領域のサイズや複雑さによっては、提供される機能ごとに最大 1 つまで、追加のファイルが必要になる場合があります。

機能が追加された (または用途が変更された) 場合は、概要ドキュメントを提供する必要があります。

このドキュメントの一部として、機能や概念を初めて使用するお客様を支援するために、使用方法に関するセクション (図を含む) を提供する必要があります。

デザインに関するドキュメント

Mixed Reality では、まったく新しい世界を創造する機会が提供されます。 これには、MRTK で使用するカスタム資産の作成が含まれる可能性があります。 これをお客様にとってできるだけ摩擦のないものにするために、コンポーネントでは、アート資産についての書式やその他の要件を記述する、設計に関するドキュメントを提供する必要があります。

設計に関するドキュメントは、次のような例で役立ちます。

• カーソル モデル
• 空間マッピングの視覚化
• 効果音ファイル

この種のドキュメントは強くお勧めします。プル要求のレビューの一環として要求することもできます。

これは、MS 開発者サイトでの設計の推奨事項とは異なる場合があります。

パフォーマンス上の注意点

一部の重要な機能にはパフォーマンス コストがかかります。 このコードは、構成方法によって大幅に異なる場合がよくあります。

次に例を示します。

When using the spatial mapping component, the performance impact will increase with the level of detail requested.  
It is recommended to use the least detail possible for the desired experience.

パフォーマンス上の注意点は、CPU または GPU の負荷の高いコンポーネントに対して推奨されており、プル要求のレビューの一環として要求される場合があります。 該当するパフォーマンスに関する注意事項については、API および概要に関するドキュメントを参照してください。

重大な変更

重大な変更に関するドキュメントは、各機能領域の個々の breaking-changes.md にリンクする最上位ファイルで構成されます。

機能領域の breaking-changes.md ファイルには、特定のリリースのすべての既知の重大な変更の一覧と、過去のリリースからの重大な変更の履歴が含まれます。

次に例を示します。

Spatial sound breaking changes

2018.07.2
* Spatialization of the imaginary effect is now required.
* Management of randomized AudioClip files requires an entropy value in the manager node.

2018.07.1
No known breaking changes

2018.07.0
...

機能レベルの breaking-changes.md ファイルに含まれる情報は、新しい MRTK リリースごとにリリース ノートに集約されます。

変更の一部である重大な変更は、プル要求の一部としてドキュメント化する必要があります。

MarkDown を編集するためのツール

Visual Studio Code は、MRTK のドキュメントの一部であるマークダウン ファイルを編集するための優れたツールです。

ドキュメントを作成する場合は、次の 2 つの拡張機能をインストールすることを強くお勧めします。

• Visual Studio Code 向けの Docs Markdown 拡張機能 - Alt + M を使用して、docs 作成オプションのメニューを表示します。

• Code Spell Checker - スペルミスの単語に下線が引かれます。スペルミスの単語を右クリックして変更するか、辞書に保存します。

これらはいずれも、Microsoft が公開しているドキュメント作成パックにパッケージ化されています。

関連項目

• ドキュメントの「関連項目」リンクの例