ドキュメント作成ガイドライン

Godotコミュニティは豊かで国際的です。ユーザーは世界中から来ています。若い人もいれば、英語を母国語としない人もいます。だからこそ、私たちは皆、明確で共通の言語を使って書かなければならないのです。クラス参照の場合、目標は、すべての人にとって読みやすく、正確に読みやすくすることです。

要約すると、常に次のように努めます:

  1. 直接的な表現を使用する
  2. 正確なアクション動詞を使用する
  3. 「-ing」で終わる動詞は避けてください
  4. 不要な副詞や形容詞を削除します。
  5. これらの8つの単語を禁止: 明白な、シンプル、基本的な、簡単、実際、ちょうど、明確、および
  6. 明示的な参照を使用する
  7. 「's」を使用して所有物を表示する
  8. オックスフォードコンマを使用する

クラスを記述する3つのルールがあります:

  1. 簡単な説明でノードの概要を説明する
  2. 役に立つ場合に返すメソッドについて言及する
  3. 「if true」を使用してブール値を記述する

注釈

テクニカルライターの仕事は、可能な限り多くの情報を可能な限り小さく、最も明確な文章に詰め込むことです。これらのガイドラインは、その目標に向かって取り組むのに役立ちます。

7 rules for clear English

直接的な表現を使用する

可能な場合は能動態を使用してください。 説明するクラス、メソッド、および定数を主題として取り上げます。 受動態を使用して書くのは自然ですが、読みにくく、長い文章を作成します。

受動態:

The man **was bitten** by the dog.

能動態:

The dog bit the man.

受動態を使用しないでください :

void edit_set_pivot ( Vector2 pivot )
[...] This method **is implemented** only in some nodes that inherit Node2D.

ノードの名前を名詞として使用してください:

void edit_set_pivot ( Vector2 pivot )
[...] Only some Node2Ds **implement** this method.

正確なアクション動詞を使用する

makeset などの一般的な動詞や、1 つの単語で置き換えることができる式よりも、正確で一般的な動詞を優先します。

メソッドの名前を繰り返さないで下さい。ピボット値を新しいピボット値に設定済みと指定しています:

void edit_set_pivot ( Vector2 pivot )
Set the pivot position of the 2D node to [code]pivot[/code] value. [...]

この「セット」の結果について説明してください。 placepositionrotatefade などの正確な動詞を使用します。

void edit_set_pivot ( Vector2 pivot )
Position the node's pivot to the [code]pivot[/code] value. [...]

「-ing」で終わる動詞は避けてください

プログレッシブフォームは、連続的なアクションを記述します。例えば「呼び出し中」、「移動中」などです。

インスタント変更にはプログレッシブフォームを使用しないでください

Vector2 move ( Vector2 rel_vec )
Move the body in the given direction, **stopping** if there is an obstacle. [...]

単純な現在形、過去分詞形、または未来を使用してください

Vector2 move ( Vector2 rel_vec )
Moves the body in the vector's direction. The body **stops** if it collides with an obstacle. [...]

プログレッシブ時制を使用して、時間的に連続するアクションを記述することができます。 アニメーションやコルーチンのようなもの。

ちなみに

動詞は-ingで形容詞的名詞になります。これは活用ではないので、 the remaining movementthe missing file などのように使用できます。

不要な副詞や形容詞を削除する

形容詞や副詞をできるだけ少なく書いてください。説明に重要な情報を追加する場合にのみ使用してください。

冗長または無意味な副詞を使用しないでください。ドキュメントを長くするが、情報を追加しない単語:

**Basically** a big texture [...]

簡単で説明的な言語で短い文章を書いて下さい:

A big texture [...]

これらの8つの単語を禁止

これらの8つの禁止単語を使用しないでください:

  1. 明らかな
  2. シンプルな
  3. 基本的な
  4. 簡単な
  5. 実際の
  6. ちょうどの
  7. はっきりとした
  8. しかし(一部の用途)

ゲームの作成とプログラミングは簡単ではありませんし、初めてAPIを使用することを学ぶ人にとって簡単なことではありません。リスト内の他の単語 ( justactual など)は、文章に情報を追加しません。対応する副詞も使用しないでください:明らかに、基本的に、簡単に、実際には、はっきりと。

例を挙げないでください。 禁止された言葉は説明を長くし、最も重要な情報から注意をそらします:

**TextureRect**
Control frame that **simply** draws an assigned texture. It can stretch or not. It's a **simple** way to **just** show an image in a UI.

それらを削除します:

**TextureRect**
[Control] node that displays a texture. The texture can stretch to the node's bounding box or stay in the center. Useful to display sprites in your UIs.

「シンプル」は決して役に立ちません。 他のユーザーにとっては、複雑なものやイライラするものがあります。 古き良き時代のようなものはありません。 古い簡単な説明は、タイマーノードのページの最初の文です:

**Timer**
A **simple** Timer node.

ノードが代わりに何を行うかを説明してください:

**Timer**
Calls a function of your choice after a certain duration.

「基本」を使用しないでください、それはあまりにもあいまいです:

**Vector3**
Vector class, which performs **basic** 3D vector math operations.

簡単な説明を使用して、ノードの概要を説明してください:

**Vector3**
Provides essential math functions to manipulate 3D vectors: cross product, normalize, rotate, etc.

明示的な参照を使用する

暗黙的な参照よりも明示的な参照を優先します。

「前者」、「後者」などの言葉を使用しないでください。これらは英語では最も一般的ではなく、リファレンスを確認する必要があります。

[code]w[/code] and [code]h[/code] define right and bottom margins. The **latter** two resize the texture so it fits in the defined margin.

言葉を繰り返してください。 それらはすべての曖昧さを取り除きます:

[code]w[/code] and [code]h[/code] define right and bottom margins. **[code]w[/code] and [code]h[/code]** resize the texture so it fits the margin.

同じ変数名を3回または4回繰り返す必要がある場合は、説明を書き換える必要があります。

「's」を使用して所有物を表示する

「The milk of the cow」を避けてください。 英語では不自然に感じます。 代わりに「The cow's milk」と書いてください。

「of the X」とは書かないでください:

The region **of the AtlasTexture that is** used.

所有格の 's使用してください。文の先頭に主語を置き、短くすることができます:

The **AtlasTexture's** used region.

オックスフォードコンマを使用して何かを列挙する

オックスフォード辞書から:

「オックスフォードコンマ」は、リストの最後にある「and」という語の前にあるオプションのコンマです。書籍、ビデオ、雑誌を販売しています。

[...] 全ての作家や出版社が使っているわけではありませんが、リストの中の項目が単一の単語ではない場合、文章の意味を明確にすることができます:これらの項目は白黒、赤と黄色、青と緑で利用できます。

コンマなしでリストの最後の要素を残さないでください:

Create a KinematicBody2D node, a CollisionShape2D node and a sprite node.

2つ以上の要素を持つリストの最後の要素に and または or の前にコンマを追加してください

Create a KinematicBody2D node, a CollisionShape2D node, and a sprite node.

メソッドとクラスの記述方法

動的な型指定と静的な型指定

ドキュメントのコード例は、ユーザーを混乱させないために一貫したスタイルに従う必要があります。静的型ヒントはGDScriptのオプション機能であるため、動的コードの記述に固執することにしました。これにより、簡潔でアクセス可能なGDScriptを作成できます。

例外は、静的型付けの概念をユーザーに説明するトピックです。

型ヒントを、コロンで追加したりキャストしたりしないでください:

const MainAttack := preload("res://fire_attack.gd")
var hit_points := 5
var name: String = "Bob"
var body_sprite := $Sprite as Sprite

動的型付けを使用して定数変数を記述します:

const MainAttack = preload("res://fire_attack.gd")
var hit_points = 5
var name = "Bob"
var body_sprite = $Sprite

推論された引数または戻り値の型を持つ関数を記述しないでください:

func choose(arguments: Array):
    # Chooses one of the arguments from array with equal chances
    randomize()
    var size := arguments.size()
    var choice: int = randi() % size
    return arguments[choice]

動的型付けを使用して関数を作成する:

func choose(arguments):
    # Chooses one of the arguments from array with equal chances
    randomize()
    var size = arguments.size()
    var choice = randi() % size
    return arguments[choice]

必要に応じて、実際のコード例を使用します

実世界の例は、抽象的な foos および bars よりも初心者にとってアクセスしやすいです。また、ゲームプロジェクトから直接コピーして、コードスニペットがエラーなしでコンパイルされるようにすることもできます。

var my_var = 10 ではなく var speed = 10 と書くと、初心者はコードをよりよく理解できます。ライブプロジェクトでコードスニペットを使用できる場所に関する参照フレームを提供します。

作成例を書かないでください:

onready var a = preload("res://MyPath")
onready var my_node = $MyNode


func foo():
    # Do stuff

具体的な例を書きます:

onready var sfx_player_gun = preload("res://Assets/Sound/SFXPlayerGun.ogg")
onready var audio_player = $Audio/AudioStreamPlayer


func play_shooting_sound():
    audio_player.stream = sfx_player_gun
    audio_player.play()

もちろん、実際の例を使用するのは実用的でない場合があります。これらの状況では、my_varfoo() ``\ 、または ``my_func() などの名前の使用を避け、例にとってより意味のある名前を検討する必要があります。

簡単な説明でノードの概要を説明する

簡単な説明は、参照の最も重要な文です。これは、ユーザーがノードと最初に接触した場合です:

  1. これは、「新しいノードを作成」ダイアログボックスの唯一の説明です。
  2. 参照内のすべてのページの一番上に表示されます

簡単な説明では、ノードの役割とその機能を最大200文字で説明する必要があります。

小さくてあいまいな要約を書かないで下さい:

**Node2D**
Base node for 2D system.

ノードの機能の概要を説明してください:

**Node2D**
2D game object, parent of all 2D related nodes. Has a position, rotation, scale and z-index.

ノードの完全な説明を使用して、詳細情報とコード例を提供します(可能であれば)。

役に立つ場合に返すメソッドについて言及する

重要な値を返すメソッドもあります。説明の最後に、理想的には新しい行でそれらを説明します。名前が set または get で始まるメソッドの戻り値を言及する必要はありません。

受動態を使用しないでください :

Vector2 move ( Vector2 rel_vec )
[...] The returned vector is how much movement was remaining before being stopped.

常に「Returns」を使用してください

Vector2 move ( Vector2 rel_vec )
[...] Returns the remaining movement before the body was stopped.

「能動態」ルールの例外に注意してください: moveメソッドを使用すると、外部コライダがメソッドと move を呼び出す本文に影響を与える可能性があります。この場合、受動態を使用できます。

「if true」を使用してブール値を記述する

ブールメンバ変数の場合は、常に `` if true`` および/または `` if false`` を使用して明示的にしてください。 「コントロールするかどうか」はあいまいである可能性があり、すべてのメンバー変数に対して機能しません。

また、ブール値、変数名、およびメソッドを [code][/code] で囲みます。

"if true" から始めてください:

Timer.autostart
If [code]true[/code], the timer will automatically start when entering the scene tree.

引数の周りに [code] を使用する

クラス参照では、引数を常に [code][/code] で囲みます。ドキュメントとGodotでは、this のように表示されます。 GodotリポジトリでXMLファイルを編集するときは、'this' や `this` などの既存の引数を [code]this[/code] に置き換えます。

Common vocabulary to use in Godot's documentation

開発者は、インターフェイスの領域を指す特定の単語を選択しました。 それらはソースやドキュメントで使用されており、同義語の代わりに常に使用する必要があります。そうすれば、ユーザーはあなたが何を話しているのかを知ることができます。

Overview of the interface and common vocabulary

インターフェイスと一般的な語彙の概要

エディタの左上隅に main menus があります。中央のボタンで workspace が変更されます。そして、右上のボタンは playtest buttons です。2Dまたは3D空間を表示する中央の領域は viewport です。上部には、 toolbar 内の tools のリストがあります。

ビューポートの両側のタブまたはドッキング可能なパネルは docks です。 FileSystem dock 、シーンツリーを含む Scene dockImport dockNode dockInspector または Inspector dock があります。 デフォルトのレイアウトでは、タブ付きドックを tabs と呼ぶことができます: Scene tabNode tab ...

ビューポートの下部にあるアニメーション、デバッガなどは panels``です。彼らは一緒に ``bottom panels を構成します。

インスペクタの折りたたみ可能な領域は sections です。折りたたむことができないノードの親クラス名は、 Classes など KinematicBody2D class です。また、キーと値のペアを持つ個々の行は properties です。例えば positionmodulate color はどちらも properties です。

Keyboard shortcut guidelines

Keyboard and mouse shortcuts should make use of the :kbd: tag, which allows shortcuts to stand out from the rest of the text and inline code. Use the compact form for modifier keys (Ctrl/Cmd) instead of their spelled out form (Control/Command). For combinations, use the + symbol with a space on either side of the symbol.

Make sure to mention shortcuts that differ on macOS compared to other platforms. On macOS, Cmd often replaces Ctrl in keyboard shortcuts.

Try to integrate the shortcut into sentences the best you can. Here are some examples with the :kbd: tag left as-is for better visibility:

  • Press :kbd:`Ctrl + Alt + T` to toggle the panel (:kbd:`Cmd + Alt + T` on macOS).
  • Press :kbd:`Space` and hold the left mouse button to pan in the 2D editor.
  • Press :kbd:`Shift + Up Arrow` to move the node upwards by 8 pixels.

画像投稿ガイドライン

ドキュメントの重要な部分はイメージであり、いくつかの重要なガイドラインに従う必要があります。

まず、スクリーンショットを撮るときは、常にデフォルトのエディタテーマとテキストを使用する必要があります。

To improve the apperance of 3D screenshots, use 4× MSAA, enable anisotropic filtering on the project's textures, and set the anisotropic filter quality to 16× in Project Settings.

Screenshot sizes should not exceed 1920×1080 to ensure fast loading on slower connections.

ボタンやオプションなど、何かを表示するためにエディタの領域を強調表示する必要がある場合は、ベベルのない2ピクセルの太さのアウトラインを使用します。

Before you add or replace any images in the documentation, they should be run through a PNG compressor to save size. The built in lossless compressor in programs like Krita or Photoshop should be enough. For heavier images, also look into using a lossy compressor, such as pngquant where almost no image quality is lost during compression.