スタイルガイド

このページでは、明確で簡潔、かつ親しみやすいドキュメントの書き方を解説します。Googleが公開している無料のTechnical Writingコース（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に固有の用語は、上記の単語を含んでいても大文字から始めてください。
  • 例: 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"）を組み合わせています。「There is」を力強い主語と動詞に置き換えることで、文章を改善しましょう。

短い文章

短い文章は、長い文章に比べて読みやすく、理解しやすく、保守もしやすいのが一般的です。

• 1つの文章につき、1つのアイデアに集中しましょう。文章に複数の考えが含まれている場合は、複数の文章に分割してください。
• 長い文章で「or」という接続詞を使う場合は、箇条書きにすることを検討してください。
• 余計なフレーズは簡潔な言葉に置き換えましょう。例えば、「at this point in time」を「now」に置き換えます。

リストとテーブル

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

• 各リストやテーブルは、それが何を表しているかを説明する一文を添えて導入してください。
• 各項目の先頭は大文字にしてください。文章にする場合は、句読点を使用してください。
• 項目同士には「関連性」を持たせるか、同じカテゴリに属するようにしてください。

以下のリストは、どの種類のリストを使用すべきかを選択する際の手引きです。

パラグラフ

Paragraphs（段落）は、複雑な概念を小さなトピックに分割することで、読者の理解を助けます。読みやすい段落を構成するためのポイントは以下の通りです。

• 優れた導入文を書く。その段落が何について書かれているかを明確にします。
• 各段落を1つのトピックに絞る。現在のトピックに関係のない文章は、移動するか削除してください。
• 長すぎる段落を避ける。文字がびっしりと詰まった塊は、読者に心理的な負担を与えます。
• 短すぎる段落を避ける。複数の段落をまとめたり、リスト形式に変更したりしてください。

読者層

ドキュメントを執筆する際は、読者が誰であり、彼らに何を学んでもらいたいかを検討してください。ほとんどの場合、以下の前提を置くことができます。

• 読者はSteam、Oculus、Pico、Android、またはiOSでVRChatにアクセスできる。
• 読者はプレイヤー、アバター、ワールド、フレンド、VR（仮想現実）といったVRChatの基本的な概念を知っている。
• 読者は英語を話すが、ネイティブスピーカーではない可能性がある。
• 読者はCreator Companionを使用して、VRChatのワールドやアバターのUnityプロジェクトを作成する方法を知っている。

VRChatの制作ドキュメントの読者層は幅広いです。入門ガイドを必要とする初心者向けのページもあれば、すでに基礎知識を備えたエキスパート向けのページもあります。読者がすでに知っている事柄については、繰り返す必要はありません。例を挙げます。

• Getting Started の読者は、SDKを使って何かを作成したいと考えています。
  • 彼らには、Creator Companionを使用してVRChat SDKのシンプルなUnityプロジェクトを作成する方法を教える必要があります。
  • VRChatとは何かを説明する必要はありません。
• Avatar Scaling の読者は、Avatars SDKの使用方法を知っています。
  • 彼らには、アバターのスケーリングにおける制限について詳細な説明を行う必要があります。
  • VRChat Avatars SDKの始め方を説明する必要はありません。

最終更新: 2024年10月22日