スタイルガイド

このページでは、明確で簡潔、かつ親しみやすいドキュメントの書き方を解説します。本書は、Googleが公開しているテクニカルライティングコース（CC BY 4.0）の要約であり、VRChatの制作ドキュメントへの応用方法を推奨するものです。

VRChatの制作ドキュメントに貢献する前に、このページを一読してください。

用語と略語

Unity、VRChat、およびVRChat SDKには、読者が馴染みのない用語が含まれていることがあります。ドキュメントを作成する際は、これらの用語を特定するようにしてください。

• 新しい用語を導入する場合は、その説明を行ってください。すでに存在する用語であれば、その説明ページへのリンクを提供してください。
  • 例：「'Marketplace'タブでは、Creator Economyを利用しているすべてのVRChatワールドを確認できます。」
• 用語は一貫して使用するようにしてください。同じ用語の類似した表記を混在させないでください。
  • 例：「GameObject」と「game object」。
• VRChatやSDKに固有の用語ではない場合は、VRChat内で特定の意味を持つ場合であっても、小文字で表記してください。
  • 例：avatar、world、creator。
• VRChat や SDK 固有の用語は、上記に含まれる単語であっても、頭文字を大文字（Capitalize）にしてください。
  • 例：Avatars SDK、Worlds SDK、VRChat、Creator Economy

文書内で頻繁に使用される用語には頭字語（アクロニム）を使用できます。初めて頭字語を使用する際は、定義してください。例：

• Software Development Kit (SDK)
• VRChat Creator Companion (VCC)
• Creator Economy (CE)

あまり使用しない用語の頭字語は定義せず、正式名称を使用してください。

能動態

ドキュメントの大部分は、受動態ではなく能動態で記述してください。以下の表は、能動態を使用することで文章がどのように読みやすくなるかを示しています。

能動態を使うと、文中の動作主を明確にできます。一方、受動態では動作主が省略されることがあります。

明確な文章

力強い動詞と主語を使用して、より明確な文章を書きましょう。力強い動詞は文章の明瞭さを高め、読者の関心を引きつけます。弱く曖昧で一般的な動詞は避けましょう。例を挙げます：

「be動詞」（is、are、was、wereなど）は、時として最善の選択肢となります。常に置き換える必要はありませんが、代替表現がないか検討する時間を取ってください。

「There is」で始まる文は、弱い主語（「There」）と弱い動詞（「is」）を組み合わせています。以下のように、強い主語と動詞に置き換えて文を改善しましょう。

短い文

短い文は、長い文に比べて、一般的に読みやすく、理解しやすく、維持管理もしやすくなります。

• 各文を一つのアイデアに絞ってください。文の中に複数の考えが含まれている場合は、複数の文に分割してください。
• 長い文の中で接続詞の「or」を使用する場合は、箇条書きにすることを検討してください。
• 冗長な表現を簡潔な言葉に置き換えてください。例えば、「at this point in time」を「now」に置き換えます。

リストと表

リストと表を使用すると、ドキュメントが理解しやすくなります。

• 各リストや表の前には導入となる一文を置いてください。それが何を表しているのかを読者に伝えます。
• 各項目の最初の文字を大文字で始めてください。文章にする場合は、句読点を付けてください。
• 各項目は、互いに関連性があるものか、同じカテゴリに属するものである必要があります。

以下のリストでは、どのタイプのリストを使用すべきかを選択する方法を説明します。

段落

段落は、複雑な概念を小さなトピックに分割することで、読者の理解を助けます。優れた段落を構成する方法は以下の通りです。

• 優れた導入文を書きましょう。その段落が何について説明しているのかを明確にする必要があります。
• 各段落では1つのトピックに焦点を絞ってください。現在のトピックに関係のない文は、移動するか削除しましょう。
• 非常に長い段落は避けましょう。文字が密集した状態は、読者に威圧感を与えます。
• 非常に短い段落は避けましょう。それらをまとめるか、リスト形式に変更してください。

## You (the reader)

ドキュメントを作成する際は、ターゲット読者が誰であるか、そして彼らに何を学んでほしいかを考慮してください。ほぼ常に前提としておける項目は以下の通りです。

• 読者は、Steam、Oculus、Pico、Android、またはiOS上でVRChatにアクセスできる環境にあるものとします。
• 読者は、プレイヤー、アバター、ワールド、フレンド、バーチャルリアリティといった、VRChatの基本的なコンセプトを理解しているものとします。
• 読者は英語を話しますが、ネイティブスピーカーではない可能性があります。
• 読者は、Creator Companion を使用して VRChat のワールドまたはアバターの Unity プロジェクトを作成する方法を知っているものとします。

VRChatの作成ドキュメントには幅広い読者がいます。初心者向けの入門ガイドを目的としたページもあれば、すでに基本を理解している専門家向けのページもあります。読者がすでに知っていることは、繰り返す必要はありません。例えば：

• Getting Startedの読者は、SDKを使って何かを作成したいと考えています。
  • Creator Companion を使って VRChat SDK でシンプルな Unity プロジェクトを作成する方法を教える必要があります。
  • VRChat とは何かを説明する必要はありません。
• Avatar Scaling のターゲット読者は、Avatars SDK の使用方法を理解しているものとします。
  • アバターのスケーリングに関する制限について、詳細な説明を求めているものとします。
  • VRChat Avatars SDK の基本的な使い方を説明する必要はありません。