Writing guidelines

Note spécifique à la traduction française * : Cette partie concerne la contribution que vous pouvez apporter à la documentation de Godot et contient, entre autre, des directives et le style à suivre. Cette partie est traduite en français mais gardez à l'esprit que le sujet est d'écrire de la documentation dans un anglais accessible. *Fin de la note.

En résumé, essayez de toujours :

1. Utiliser la voix active

2. Utiliser des verbes d'action précis

3. Évitez les verbes qui se terminent par -ing

4. Supprimer les adverbes et adjectifs inutiles.

5. Interdire ces 8 mots : évident, simple, basique, facile, réel, juste, clair, cependant

6. L'utilisation de références explicites

7. L'utilisation de 's pour montrer la possession

8. Utilisez la virgule d'Oxford

Il existe 3 règles pour décrire les classes :

1. Donnez un aperçu du nœud dans la brève description

2. Mentionner quelles méthodes retournent un résulat si elles c'est utiles

3. Utilisez "si vrai" pour décrire les booléens

Note

Le travail d'un rédacteur technique consiste à regrouper le plus d'informations possible dans des phrases les plus petites et les plus claires possibles. Les présentes lignes directrices vous aideront à atteindre cet objectif.

Voir aussi

Consultez les directives relatives au contenu pour obtenir des informations sur les types de documentation que vous pouvez écrire dans la documentation officielle.

7 règles pour un anglais clair

Utiliser la voix active

Utilisez la voix active lorsque c'est possible. Prenez les classes, les méthodes, et les constantes que vous décrivez comme sujet. Il est naturel d'écrire à l'aide de la voix passive, mais c'est plus difficile à lire et produit des phrases plus longues.

Passive :

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

Active :

The dog bit the man.

N'utilisez pas la voix passive :

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

Utilisez utilisez le nom du nœud comme nom :

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

Utiliser des verbes d'action précis

Privilégiez les verbes précis mais courants aux verbes génériques comme make, set, et toute expression que vous pouvez remplacer par un seul mot.

Ne répétez pas le nom de la méthode. Il indique déjà qu'il change la valeur pivot :

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

Expliquez quelle est la conséquence de ce "set" : utilisez des verbes précis comme place, position, rotate, fade, etc.

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

Évitez les verbes qui se terminent par -ing

Les formes progressives décrivent des actions continues. Par exemple, "is calling", "is moving".

N'utilisez pas la forme progressive pour des changements instantanés.

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

Utilisez présent simple, passé ou futur.

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

Exception : Si le sujet n'est pas clair, le remplacement des verbes "ing" n'est pas une amélioration. Par exemple, dans la phrase précédente, "it replaces" n'aurait pas beaucoup de sens là où "replacing" se trouve actuellement.

Vous pouvez utiliser le temps progressif pour décrire des actions qui sont continues dans le temps. Tout comme l'animation ou les coroutines.

Astuce

Les verbes peuvent se transformer en noms adjectifs avec -ing. Il ne s'agit pas d'une conjugaison, vous pouvez donc les utiliser : the remaining movement, the missing file, etc.

Supprimer les adverbes et adjectifs inutiles

Écrivez le moins d'adjectifs et d'adverbes possible. Ne les utilisez que s'ils ajoutent des informations clés à la description.

N'utilisez pas d'adverbes redondants ou dénués de sens. Des mots qui allongent la documentation mais n'ajoutent aucune information :

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

Utilisez des phrases courtes dans un langage simple et descriptif :

A big texture [...]

Bannissez ces 8 mots

N'utilisez jamais ces 8 mots :

1. évident

2. simple

3. basique/ de base

4. facile

5. actuel

6. juste

7. clair/clairement

8. cependant (certains usages)

La création et la programmation de jeux n'est pas facile, et rien n'est facile pour quelqu'un qui apprend à utiliser l'API pour la première fois. D'autres mots de la liste, comme juste(just) ou actuel(actual) n'ajouteront aucune information à la phrase. N'utilisez pas non plus d'adverbes correspondants : évidemment, simplement, fondamentalement, facilement, en fait, clairement(obviously, simply, basically, easily, actually, clearly).

Ne pas faire exemple. Les mots interdits allongent la description et détournent l'attention des informations les plus importantes :

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

Faire les supprimer :

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

Le mot "simple" n'aide jamais. N'oubliez pas que pour les autres utilisateurs, tout peut être complexe ou les frustrer. Il n'y a rien de tel qu'un bon vieux c'est simple pour vous faire craquer. Voici l'ancienne brève description, la première phrase de la page du nœud Timer :

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

** Expliquez** ce que fait le nœud à la place :

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

N'utilisez pas "de base", c'est trop vague :

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

Utilisez la brève description pour donner un aperçu du nœud :

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

L'utilisation de références explicites

Privilégier les références explicites aux références implicites.

N'utilisez pas d'expression comme "le premier", "le second", etc. Ils ne sont pas les plus courants en anglais, et ils vous obligent à vérifier la référence.

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

Faire répéter des mots. Ils suppriment toute ambiguïté :

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

Si vous devez répéter le même nom de variable 3 ou 4 fois, vous devez probablement reformuler votre description.

L'utilisation de 's pour montrer la possession

Évitez "The milk of the cow". En anglais, cela semble non-naturel. Écrivez plutôt "The cow's milk".

Ne pas faire écrire "of the X" :

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

Faire Utilisez les 's. Cela vous permet de mettre le sujet principal au début de la phrase, et de la garder courte :

The **AtlasTexture's** used region.

Utilisez la virgule d'Oxford pour énumérer quoi que ce soit

Tiré du dictionnaire Oxford :

La "virgule d'Oxford" est une virgule facultative qui précède le mot "et" à la fin d'une liste : Nous vendons des livres, des vidéos, et des magazines.

[...] Tous les écrivains et éditeurs ne l'utilisent pas, mais il peut clarifier le sens d'une phrase lorsque les éléments d'une liste ne sont pas des mots isolés : Ces éléments sont disponibles en noir et blanc, rouge et jaune, et bleu et vert.

Ne laissez pas le dernier élément d'une liste sans virgule :

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

Ajoutez une virgule avant et ou ou, pour le dernier élément d'une liste comportant plus de deux éléments.

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

Comment rédiger des méthodes et des classes

Typage dynamique vs statique

Les exemples de code dans la documentation doivent suivre un style cohérent pour ne pas troubler les utilisateurs. Comme les indications de type statique sont une caractéristique optionnelle du GDScript, nous avons choisi de nous en tenir à l'écriture de code dynamique. Cela nous a permis d'écrire un GDScript concis et accessible.

Les sujets qui expliquent aux utilisateurs les concepts d'écriture de code statique font exception.

Ne pas faire ajouter une indication de type avec deux points ou par conversion :

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

Faire écrire des variables consistante avec le typage dynamique :

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

Ne pas faire écrire de fonctions avec des arguments inférés ou des types de retour :

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]

Faire écrire des fonctions en utilisant la frappe dynamique :

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]

Utiliser des exemples de codes du monde réel, quand c'est approprié

Les exemples du monde réel sont plus accessibles aux débutants que les foos et bars abstraits. Vous pouvez également les copier directement à partir de vos projets de jeu, en vous assurant que tout extrait de code se compile sans erreur.

Le fait d'écrire var speed = 10 plutôt que var my_var = 10 permet aux débutants de mieux comprendre le code. Il leur donne un cadre de référence pour utiliser les extraits de code dans un projet en direct.

N'écrivez pas d'exemples inventés :

@onready var a = preload("res://MyPath")
@onready var my_node = $MyNode


func foo():
    # Do stuff

Écrivez des exemples concrets :

@onready var sfx_player_gun = preload("res://Assets/Sound/SFXPlayerGun.ogg")
@onready var audio_player = $Audio/AudioStreamPlayer


func play_shooting_sound():
    audio_player.stream = sfx_player_gun
    audio_player.play()

Bien sûr, il y a des moments où il n'est pas pratique d'utiliser des exemples réels. Dans ces situations, vous devriez quand même éviter d'utiliser des noms tels que my_var, foo() ou my_func() et envisager des noms plus significatifs pour vos exemples.

Donnez un aperçu du nœud dans la brève description

La brève description est la phrase la plus importante de la référence. C'est le premier contact de l'utilisateur avec un nœud :

1. C'est la seule description dans le dialogue "Créer un nouveau nœud".

2. Il se trouve en haut de chaque page de la référence

La brève description doit expliquer le rôle du nœud et sa fonctionnalité, en 200 caractères maximum.

Ne faites pas de résumés petits et vagues :

**Node2D**
Base node for 2D system.

Donner un aperçu de la fonctionnalité du nœud :

**Node2D**
A 2D game object, inherited by all 2D-related nodes. Has a position, rotation, scale, and Z index.

Utilisez la description complète du nœud pour fournir plus d'informations, et un exemple de code, si possible.

Mentionner quelles méthodes retournent un résulat si elles c'est utiles

Certaines méthodes renvoient des valeurs importantes. Décrivez-les à la fin de la description, idéalement sur une nouvelle ligne. Il n'est pas nécessaire de mentionner les valeurs de retour pour toute méthode dont le nom commence par "set" ou "get".

N'utilisez pas la voix passive :

Vector2 move ( Vector2 rel_vec )
[...] The returned vector is how much movement was remaining before being stopped.

Toujours utilisez « Retourne ».

Vector2 move ( Vector2 rel_vec )
[...] Returns the remaining movement before the body was stopped.

Remarquez l'exception à la règle de la "voix directe" : avec la méthode de déplacement, un collisionneur externe peut influencer la méthode et le corps qui appelle move. Dans ce cas, vous pouvez utiliser la voix passive.

Utilisez "si vrai" pour décrire les booléens

Pour les variables membres booléennes, utilisez toujours si vrai et/ou si faux, pour rester explicite. Les contrôles si vrai ou si faux peuvent être ambigus et ne fonctionneront pas pour chaque variable membre.

De plus, entourez les valeurs booléennes, les noms de variables et les méthodes avec [code][/code].

Commencez par si vrai :

Timer.autostart
If [code]true[/code], the timer will automatically start when entering the scene tree.

Utiliser [code] autour des arguments

Dans la référence de classe, entourez toujours les arguments par [code][/code]. Dans la documentation et dans Godot, il s'affichera comme ceci. Lorsque vous éditez des fichiers XML dans le dépôt Godot, remplacez les arguments existants écrits comme 'ceci' ou `ceci` par [code]ceci[/code].

Vocabulaire commun à utiliser dans la documentation de Godot

Les développeurs ont choisi certains mots spécifiques pour désigner les zones de l'interface. Ils sont utilisés dans les sources, dans la documentation, et vous devriez toujours les utiliser au lieu de synonymes, afin que les utilisateurs sachent de quoi vous parlez.

Aperçu de l'interface et du vocabulaire commun

Dans le coin supérieur gauche de l'éditeur se trouvent les main menus. Au centre, les boutons changent le workspace. Et ensemble, les boutons en haut à droite sont les playtest buttons. La zone au centre, qui affiche l'espace 2D ou 3D, est le viewport. En haut, vous trouverez une liste de tools dans la toolbar.

Les onglets ou panneaux ancrables de chaque côté de la fenêtre de visualisation sont des docks. Vous avez le dock FileSystem dock, le Scene dock qui contient votre arbre de scènes, le Import dock, le Node dock et le Inspector ou Inspector dock. Avec la disposition par défaut, vous pouvez appeler les docks à onglets tabs : Scene tab, Node tab...

L'animation, le débogueur, etc. en bas de la fenêtre de visualisation (viewport) il y a des panels. Ensemble, ils forment les bottom panels.

Les zones dépliables de l'inspecteur sont des sections. Les noms des classes parentes du nœud, que vous ne pouvez pas réduire, sont des Classes, par ex. la classe CharacterBody2D. Et les lignes individuelles avec des paires clé-valeur sont des properties. Par exemple, position ou modulate color sont toutes deux des properties.

Consignes relatives aux raccourcis clavier

Les raccourcis clavier et souris doivent utiliser la balise :kbd:, qui permet aux raccourcis de se démarquer du reste du texte et des ligne de code. Utilisez la forme compacte pour les touches de modification (Ctrl/Cmd) au lieu de leur forme orthographiée (Control/Command). Pour les combinaisons, utilisez le symbole + avec un espace de chaque côté du symbole.

Assurez-vous de mentionner les raccourcis qui diffèrent sur macOS par rapport aux autres plateformes. Vous pouvez trouver une liste de tous les raccourcis, y compris ce qu'ils sont sur macOS, sur cette page.

Essayez d'intégrer le raccourci dans les phrases du mieux que vous pouvez. Voici quelques exemples avec la balise :kbd: laissée telle quelle pour une meilleure visibilité :

• Appuyez sur :kbd:`Ctrl + Alt + T` pour basculer le panneau (:kbd:`Cmd + Alt + T` sur macOS).

• Appuyez sur :kbd:`Space` et maintenez le bouton gauche de la souris enfoncé pour se déplacer dans l'éditeur 2D.

• Appuyez sur :kbd:`Shift + Up Arrow` pour déplacer le nœud vers le haut de 8 pixels.

Manual style guidelines

Follow these formatting and style guidelines when writing the manual.

Use your best judgement. If you can write more clearly by breaking one of these guidelines, please do! But remember that the guidelines exist for a reason.

Note

In many cases, the manual does not follow these guidelines. If you are already making changes to a paragraph or section of the docs, update it to follow these standards. Avoid making unrelated changes that only update style, since every change will require the paragraph to be re-translated.

Text styles

There are a few styles that the manual uses.

Style	RST formatting	Typical usage
Plaintext	texte	Used for most text.
Italique	*texte*	Used for emphasis. Used for introducing new terms.
Bold	**texte**	Used for emphasis, and for editor UI like menus and windows.
Code	`` texte ``	Used for variable names, literal values, and code snippets. code is used in many cases where you would use "quoted plaintext" in typical English.
"Guillemets"	"texte"	Used for some literal or quoted values. In many cases, another style is preferred.

Emphasis

Use either bold style or italic style to emphasize words or sentences. In most cases, either bold or italics is fine. Use whichever seems best, or whatever the page already uses.

Prefer using bold style for simple emphasis.

• Do not close the window without saving first.

Use italic style or to emphasize one word in the context of a sentence.

• You can add a node to the scene (but you can't connect one).

• You can add a node to the scene (but you can't add a resource).

• You can add a node to the scene (but you can't add one to a resource).

Use italic style when introducing new technical terms. Bold style is fine too.

• Godot uses nodes with scripts in a scene tree.

• Godot uses nodes with scripts in a scene tree.

Littéraux

Use code style for literal values. Literals include:

• Integer or int literals like 0, -2, or 100

• Float literals like 0.0, 0.5, -2.0, or 100.0

• Vector literals like (0.0, 0.0), (0.5, -0.5, 0.5), or (1.0, 2.0, 3.0, 4.0).

Classes, propriétés et méthodes

Link to classes the first time that you mention them in a page. After the first mention, use code style. For common classes, like Node, Control, or Viewport, you can also use plaintext.

Link to class members (properties, methods, enums, and constants) the first time that you mention them in a page. After the first mention, use code style. If the class member is very common, like a Node2D's position, you don't have to link.

Lorsque vous discutez des propriétés dans le contexte de l'inspecteur, utilisez plutôt le style en gras.

Editor UI

Use bold style for editor UI, including window titles, menus, buttons, input fields, inspector properties, and inspector sections. Use the exact capitalization that the editor uses.

• Ouvrir la fenêtre Paramètres de l'éditeur.

• Press the Confirm button.

• Change the node's Transform > Position property to (0, 0).

• In the Project Settings window, enable the Advanced Settings toggle.

Use Bold > With > Separators when describing sequence of menus that the reader must navigate. Use > as a separator. You can omit ellipses in menu names.

• Dans Projet > Paramètres du projet > Contrôles, ajoutez une nouvelle action d'entrée.

• Select Scene > Export As... > MeshLibrary....

• Select Scene > Export As > MeshLibrary.

Note

Sometimes, -> or → is used as a separator. This is nonstandard. Replace it with > if you are already making changes to a section.

Project settings

Link to individual project settings. Either include the section and subsection in the link itself, or include the section and subsection separately from the link. Since long links are not split into multiple lines when the page is rendered, prefer splitting the setting name and the section when the link is long.

• Set the Application > Run > Max FPS setting to 60.

• In the project settings under Application > Run, set Max FPS to 60.

• In Project Settings > Application > Run, set Max FPS to 60.

Manually wrapping lines

In the manual, lines must be manually wrapped to no more than 80-100 characters per line. However, links must not be split into multiple lines, and can exceed 100 characters. Tables can also exceed 100 characters.

When making small changes, you don't need to manually re-wrap the whole paragraph, as long as the lines don't exceed 100 characters.

Mauvais : La longueur de la ligne dépasse les 100 caractères :

The best thing to do is to wrap lines to under 80 characters per line. Wrapping to around 80-90 characters per line is also fine.
If your lines exceed 100 characters, you definitely need to add a newline! Don't forget to remove trailing whitespace when you do.

Bon : Les lignes sont limitées à 80-90 caractères :

The best thing to do is to wrap lines to under 80 characters per line. Wrapping to
around 80-90 characters per line is also fine. If your lines exceed 100 characters, you
definitely need to add a newline! Don't forget to remove trailing whitespace when you do.

Le mieux : Les lignes sont limitées à moins de 80 caractères :

The best thing to do is to wrap lines to under 80 characters per line. Wrapping
to around 80-90 characters per line is also fine. If your lines exceed 100
characters, you definitely need to add a newline! Don't forget to remove
trailing whitespace when you do.

Astuce

In most text editors, you can add a vertical guide or "ruler" at 80 characters. For example, in Visual Studio Code, you can add the following to your settings.json to add rulers at 80 and 100 characters:

"editor.rulers": [80,100],

Section header syntax

Use the following syntax for section headers:

Page title
==========

Renders as h1.
Every page has this.

Section header
--------------

Renders as h2.
Usually appears in sidebar. Many pages only need one level of nested headers.

Sub-section header
~~~~~~~~~~~~~~~~~~

Renders as h3.
Appears in sidebar in some pages, depending on how deeply nested the page is.

Sub-sub-section header
^^^^^^^^^^^^^^^^^^^^^^

Renders as h4.
Usually won't appear in the sidebar.

Currently, there are no cases of deeper header nesting than this. Avoid introducing any deeper nesting.

Note that headers have no inherent meaning. In reStructuredText, headers are parsed based on the order that they initially appear within a page. Make sure that if you use an h3 section header (~~~), you include an h2 sub-section header (---) first.

See the Sphinx documentation and the reStructuredText documentation for more information.

Quand se référer à une version de Godot spécifique

Most of the time, the class reference and the manual should not specify the first version in which a feature is added. This is because the documentation describes the current features of the engine. Documentation will be read and maintained for many versions after it is initially written, and a reference to a first supported version is only relevant for a few versions after a feature is added. After that, it becomes historical trivia best left to a dedicated changelog.

Suivez ces lignes directrices pour quand se référer à une version de Godot spécifique :

• Si une fonctionnalité a été ajoutée dans la version majeure actuelle (4.x), vous pouvez spécifier que la fonctionnalité est nouvelle en 4.x.

• Si une fonctionnalité ou une approche par défaut d'un problème a été changée entre les versions majeures (3.x -> 4.x), décrivez la fonctionnalité courante dans le corps principal de la page, et ajoutez éventuellement une brève phrase ou bloc de note pour comparer la 3.x et la 4.x.

• Si une grande fonctionnalité est ajoutée dans une version mineure 4.x, vous pouvez spécifier la version mineure de quand elle a été ajoutée. Les grandes fonctionnalités ont une page entière ou une grande section de documentation. Dans de nombreux cas, il faut encore l'éviter, car ce n'est pertinent que pour les prochaines versions mineures.

• Si une petite fonctionnalité est ajoutée dans une version mineure 4.x, ne spécifiez pas la version mineure de quand elle a été ajoutée. Les petites fonctionnalités n'ont qu'une courte section de documentation, ou sont des ajouts mineurs aux fonctionnalités existantes.

• Si l'approche par défaut d'un problème est modifiée dans une version mineure 4.x, spécifiez la version mineure dans laquelle une nouvelle approche par défaut a été ajoutée. Par exemple, le changement de TileMap à TileMapLayer dans la 4.3.

• Si une fonctionnalité a été ajoutée dans une version 3.x majeure ou mineure, ne spécifiez pas quand la fonctionnalité a été ajoutée. Ces fonctionnalités sont assez anciennes pour que la version exacte dans laquelle elles ont été ajoutées ne soit pas pertinente.