Contributing to the documentation

GDevelop's documentation is powered by the community and everyone is encouraged to contribute.

This page provides a few guidelines to help maintain the quality of the documentation.

Be consistent

Look at the existing documentation and follow the established patterns. Don't try to reinvent the wheel in terms of how the content is structured, formatted, and written.

Be concise

Use simple language, short sentences, and fewer words. If you're not sure if your writing is too wordy, use a tool like Hemingway or Grammarly to check it.

Be professional

Write with a friendly tone, but don't go overboard. If you're too casual, readers may find the writing difficult to read or trust.

For example, don't write this:

So a Text object is as the name implies something that you can use to display a text on the screen. GDevelop even allows you to change the font. the size and tons of effects! And you can also use events to make some changes on properties.

Instead, write this:

Text objects display text on screen. You can customize text properties (for example, size and color) upon creation. You can also modify text object properties during gameplay using events.

Create separate pages of concepts, tasks, and reference documentation

There are three types of documentation:

  • Concept - Explains what something is.
  • Task - Explains how to do something.
  • Reference - Provides a list of facts without (much) explanation.

Generally speaking, it's best not to blend different types of documentation in a single page. You shouldn't, for instance, provide a detailed explanation of what expressions are (concept) on the same page that you provide a list of all the expressions (reference).

When different types of documentation are on different pages, the documentation is more modular, which makes it easier to read, browse, and maintain.

Write clear, action-oriented headings

Readers tend to scan pages, so clear headings are essential. Readers also tend to care about accomplishing a specific task, so headings should focus on an action.

For example, don't write this:

Admob

Instead, write this:

Integrating ads using Google Admob

This advice applies to all of a page's headings.

Use Markdown

Markdown is a syntax for formatting text on the web. It's simple, easy to learn, and lets us move the content between different publishing platforms (if that's ever necessary).

Don't use features specific to the wiki software, such as the WRAP tag.

When in doubt, follow the Google style guide

If you're not sure how to write or format something, refer to the Google developer documentation style guide. It's a big guide, so you're not expected to memorize it, but it works great as a reference.