This page explains our writing style and the guidelines we follow to write clearly.
Our style aims at being accessible, clear, and informative, with a touch of personality. It supports our mission and goals:
The tone of an article helps to keep readers interested and engaged. It also shows our personality.
Our tone is kind, genuine, clear, accessible, inclusive, and professional.
To achieve that, avoid exaggerations, unnecessary jargon, but also colloquial expressions.
Write as if you were addressing a fellow professional or an adult student directly in a one-on-one setting. Aim for a welcoming feel without being overly close.
Address the reader directly with “you.” When talking about yourself or the team, you can use “I” or “we.” When talking about third parties, favor pronouns like “they” or “them.”
Also, while we should keep the style of documents like these consistent and formal, you’re encouraged to show your personality in news posts and devlogs.
Here is the tutorial writing workflow we should always follow. In short:
Working with an editor is essential to get the perspective of someone who hasn’t researched the subject matter as much as you did. Also, we cannot pick up all the mistakes we do alone.
Explain where you are going or why you design your code or nodes in a certain way in the introduction, before giving step-by-step instructions. This background is a vital part of the tutorial to me.
Depending on the topic, focus on:
Explaining underlying causes or concepts helps the reader to follow along and to stress the most important aspects to learn: problem-solving, transferable knowledge and techniques.
Then, you can break down the steps to reach the tutorial’s goal. You can also add general explanations or background to the rest of the tutorial.
Below, you will find specific guidelines that help to communicate ideas clearly to a broad audience, including non-native English speakers.
For technical writing, that is to say, manuals and code references, we also follow the Godot technical writing guidelines.
To start with, use American English. It is the standard in technical writing and for many free software projects.
Write with learners in your audience who understand the topic the least in mind. Doing so makes your articles more accessible, it shows your mastery, and it saves the readers’ time.
Here are some tips to achieve that goal:
For reference, check out the US government’s list of simple word alternatives.
Using the direct voice leads to shorter sentences compared to the passive voice. It makes the action clear from the first few words.
Avoid the passive voice:
The update_items function is used by the inventory system.
Favor the direct voice:
The inventory system uses the update_items function.
Keep sentences under 25 words. Favor short sentences, that each communicates one idea.
Use paragraphs to group sentences related to a broader idea together. Whenever you change the topic or move on to another concept, add a new paragraph.
Long paragraphs, like long sentences, make the text harder to follow. Give the reader a breathing room and structure your articles in a way that supports your story.
Use headings, lists, and short paragraphs to structure your writings.
Do not start a sentence with pronouns like “this” or “that” alone. Too often, these pronouns are ambiguous.
Avoid ambiguous pronouns:
Update the
velocityand callmove_and_slide(). This makes the character move.
In the sentence above, “This” could refer to updating the velocity, calling move_and_slide(), or both.
Instead, specify what the pronoun refers to:
Update the
velocityand callmove_and_slide(). This function makes the character move.
The following guidelines are more specific to writing code documentation and tutorials. We share some conventions between the two for consistency.
In technical writing, we almost always use the present tense. Depending on the case, you can replace “will” with the present tense, “let’s,” or “be + going to.”
Lastly, in cases where you cannot avoid the future tense, consider using “should” instead of “will” to suggest that something is likely to happen, rather than certain.
Write numbers in words when counting objects, except if the numbers in question refer to a value in the code.
For example:
Create two
Controlnodes as siblings. Resize the first node to take two-thirds of the viewport’s width.
Here is an example with code:
Set the
max_healthto5.
Write keywords or expressions as they appear in the interface or for the user in italics. Doing so differentiates the words from inline code.
For example, Godot capitalizes property names and settings by default. For example:
In the Initial Velocity category, change the Velocity‘s
xto-100.
Avoid replacing words like “and” with “&,” or using the slash “/” instead of “or.”
This section focuses on the structure of tutorials, articles, and HTML elements.
Use Title Case for document titles: “Getting Started with Godot.” For other headings, only capitalize the first word: “Coding the character.”
Always write a paragraph after a heading, including an introduction following a page’s title.
On the web, only the document’s title should use an H1 heading. Use H2 for sections, and H3 for sub-sections. Avoid nesting sub-sections past the H4 level.
For links, write a label that describes the action the user is taking, or the page they are going to arrive on. For example, instead of official Twitter account, use follow GDQuest on Twitter.
Some more tips:
Our guidelines are inspired by: