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.
Below, you will find specific guidelines that help to communicate ideas clearly to a broad audience, including non-native English speakers.
For technical writing, i.e. 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 for learners in your audience who understand the topic the least. This makes your articles more accessible, it shows your mastery, and it saves the readers’ time.
Here are some tips to do so:
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 breathing room and structure your articles in a way that supports your story.
Use headings, lists, and short paragraphs to structure your writings.
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 will arrive on. For example, instead of official Twitter account, use follow GDQuest on Twitter.
Some more tips:
Our guidelines are inspired by: