Writing guidelines

The Godot community is rich and international. Users come from all around the world. Some of them are young, and many aren't native English speakers. That's why we must all write using a clear and a common language. For the class reference, the goal is to make it easy to read for everyone and precise.

In summary, always try to:

  1. Use the active voice

  2. Use precise action verbs

  3. Avoid verbs that end in -ing

  4. Remove unnecessary adverbs and adjectives.

  5. Ban these 8 words: obvious, simple, basic, easy, actual, just, clear, and however

  6. Use explicit references

  7. Use 's to show possession

  8. Use the Oxford comma

There are 3 rules to describe classes:

  1. Give an overview of the node in the brief description

  2. Mention what methods return if it's useful

  3. Use "if true" to describe booleans

Note

A technical writer's job is to pack as much information as possible into the smallest and clearest sentences possible. These guidelines will help you work towards that goal.

See also

See the content guidelines for information on the types of documentation you can write in the official documentation.

7 rules for clear English

Use the active voice

Use the active voice when possible. Take the classes, methods, and constants you describe as the subject. It's natural to write using the passive voice, but it's harder to read and produces longer sentences.

Passive:

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

Active:

The dog bit the man.

Don't use the passive voice:

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

Do use the node's name as a noun:

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

Use precise action verbs

Favor precise yet common verbs over generic ones like make, set, and any expression you can replace with a single word.

Don't repeat the method's name. It already states it sets the pivot value to a new one:

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

Do explain what's the consequence of this "set": use precise verbs like place, position, rotate, fade, etc.

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

Avoid verbs that end in -ing

The progressive forms describe continuous actions. E.g. "is calling", "is moving".

Don't use the progressive form for instant changes.

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

Do use simple present, past, or future.

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

Exception: If the subject is not clear, replacing "ing" verbs is not an improvement. For example, in the previous sentence, "it replaces" would not make much sense where "replacing" currently is.

You may use the progressive tense to describe actions that are continuous in time. Anything like animation or coroutines.

Tip

Verbs can turn into adjectival nouns with -ing. This is not a conjugation, so you may use them: the remaining movement, the missing file, etc.

Remove unnecessary adverbs and adjectives

Write as few adjectives and adverbs as possible. Only use them if they add key information to the description.

Don't use redundant or meaningless adverbs. Words that lengthen the documentation but don't add any information:

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

Do write short sentences in a simple, descriptive language:

A big texture [...]

Ban these 8 words

Don't ever use these 8 banned words:

  1. obvious

  2. simple

  3. basic

  4. easy

  5. actual

  6. just

  7. clear

  8. however (some uses)

Game creation and programming aren't simple, and nothing's easy to someone learning to use the API for the first time. Other words in the list, like just or actual won't add any info to the sentence. Don't use corresponding adverbs either: obviously, simply, basically, easily, actually, clearly.

Don't example. The banned words lengthen the description and take attention away from the most important info:

**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.

Do remove them:

**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.

"Simple" never helps. Remember, for other users, anything could be complex or frustrate them. There's nothing like a good old it's simple to make you cringe. Here's the old brief description, the first sentence on the Timer node's page:

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

Do explain what the node does instead:

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

Don't use "basic", it is too vague:

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

Do use the brief description to offer an overview of the node:

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

Use explicit references

Favor explicit references over implicit ones.

Don't use words like "the former", "the latter", etc. They're not the most common in English, and they require you to check the reference.

[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.

Do repeat words. They remove all ambiguity:

[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.

If you need to repeat the same variable name 3 or 4 times, you probably need to rephrase your description.

Use 's to show possession

Avoid "The milk of the cow". It feels unnatural in English. Write "The cow's milk" instead.

Don't write "of the X":

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

Do use 's. It lets you put the main subject at the start of the sentence, and keep it short:

The **AtlasTexture's** used region.

Use the Oxford comma to enumerate anything

From the Oxford dictionary:

The 'Oxford comma' is an optional comma before the word 'and' at the end of a list: We sell books, videos, and magazines.

[...] Not all writers and publishers use it, but it can clarify the meaning of a sentence when the items in a list are not single words: These items are available in black and white, red and yellow, and blue and green.

Don't leave the last element of a list without a comma:

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

Do add a comma before and or or, for the last element of a list with more than two elements.

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

How to write methods and classes

Dynamic vs static typing

The code examples in the documentation should follow a consistent style not to confuse users. As static type hints are an optional feature of GDScript, we chose to stick to writing dynamic code. This leads to writing GDScript that is concise and accessible.

The exception is topics that explain static typing concepts to users.

Don't add a type hint with a colon or by casting:

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

Do write constants and variables with dynamic typing:

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

Don't write functions with inferred arguments or return types:

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

Do write functions using dynamic typing:

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]

Use real-world code examples where appropriate

Real-world examples are more accessible to beginners than abstract foos and bars. You can also copy them directly from your game projects, ensuring that any code snippet compiles without errors.

Writing