Writing guidelines

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:

  1. Bringing people together. Making them feel welcome and fostering collaboration.
  2. Sharing openly. We share our knowledge and tools, giving back to the community.

Our Tone

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.

Dos and don’ts

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 the least experienced reader

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:

  1. Avoid technical jargon and uncommon concepts.
  2. Use fundamental concepts to break down complex or abstract ideas.
  3. Use plain language rather than uncommon words.
  4. Be as clear and as precise as you can.

For reference, check out the US government’s list of simple word alternatives.

Use the direct voice

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 short

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.

Break up paragraphs

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.

Structure

This section focuses on the structure of tutorials, articles, and HTML elements.

Headings

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:

  • Explain where the links lead and why through their label.
  • Links should help the user scan the page for key information and related resources.

Resources

Our guidelines are inspired by:

  1. The Harvard writing guide.
  2. The US government’s plain language guidelines.
  3. Write the Docs’s style guides section for technical writers.