Directives pour la rédaction de documentation

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

7 règles pour un anglais clair

Utiliser la voix directe

L'utilisation de la voix directe lorsque c'est possible. De prendre les classes, les méthodes, et les constantes de vous décrire le sujet. Il est naturel d'écrire à l'aide de la voix passive, mais c'est plus difficile à lire et produit des phrases plus longue.

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, prétérit 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: If the subject is not clear, replacing "ing" verbs is not an improvement. For example, in the previous sentence, "it replaces" would not make much sense where "replacing" currently is.

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

N'ajoutez pas 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 := $Sprite as Sprite

** Écrivez** des variables consistante avec le typage dynamique :

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

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

func choose(arguments: Array):
    # Chooses one of the arguments from array with equal chances
    randomize()
    var size := arguments.size()
    var choice: int = randi() % size
    return arguments[choice]

Do é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**
2D game object, parent of 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.

Faire utilisez toujours "Returns".

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 `this` par [code]this[/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.

Overview of the interface and common vocabulary

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 noeud, que vous ne pouvez pas plier, sont des Classes, par exemple la classe KinematicBody2D class. 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.

Veillez à mentionner les raccourcis qui diffèrent sur macOS par rapport aux autres plateformes. Sur macOS, Cmd remplace souvent Ctrl dans les raccourcis clavier.

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.

Directives pour les contributions avec image

Une partie importante de la documentation est constituée d'images, et il y a plusieurs directives importantes à suivre.

Tout d'abord, vous devriez toujours utiliser le thème et le texte par défaut de l'éditeur lors de la prise de captures d'écran.

Pour améliorer l'apparence des captures d'écran en 3D, utilisez 4× MSAA, activez le filtrage anisotrope sur les textures du projet et réglez la qualité du filtre anisotrope à 16× dans les paramètres du projet.

La taille des captures d'écran ne doit pas dépasser 1920×1080 pour assurer un chargement rapide sur les connexions plus lentes.

Lorsque vous devez mettre en évidence une zone de l'éditeur pour afficher quelque chose, comme un bouton ou une option, utilisez un contour de 2 pixels d'épaisseur sans biseau.

Avant d'ajouter ou de remplacer des images dans la documentation, il faut les faire passer par un compresseur PNG pour en réduire la taille. Le compresseur sans perte intégré dans des programmes comme Krita ou Photoshop devrait suffire. Pour les images plus lourdes, envisagez également d'utiliser un compresseur avec perte, tel que pngquant où presque aucune qualité d'image n'est perdue pendant la compression.