Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Directives relatives au contenu

This document outlines what should be included in the official documentation. Below, you will find a couple of principles and recommendations for writing accessible content.

Nous visons deux objectifs :

  1. Faites preuve d'empathie envers nos utilisateurs. Nous devons écrire d'une manière qui leur permette d'apprendre facilement à partir des documents.

  2. Write a complete reference manual. Our goal here is not to teach programming fundamentals. Instead, our goal is to provide a reference for how Godot's features work.

Lignes directrices et principes

Below are the guidelines we should strive to follow. They are not hard rules, though: sometimes, a topic will require breaking one or more of them. Still, we should strive to achieve the two goals listed above.

Rédiger une documentation complète et accessible

Une fonctionnalité n'existe pas si elle n'est pas documentée. Si un utilisateur ne peut pas trouver d'informations sur une fonctionnalité et son fonctionnement, elle n'existe pas pour lui. Nous devons nous assurer que nous couvrons tout ce que Godot fait.

Note

Lorsqu'une fonctionnalité du moteur est ajoutée ou mise à jour, l'équipe de documentation doit en être informée. Les contributeurs doivent ouvrir une question sur le dépôt godot-docs lorsque leur travail est fusionné et nécessite une documentation.

Do your best to keep documents under 1000 words in length. If a page goes past that threshold, consider splitting it into two parts. Limiting page size forces us to write concisely and to break up large documents so that each page focuses on a particular problem.

Each page or section of a page should clearly state what problem it tackles and what it will teach the user. Users need to know if they're reading the correct guide for solving the problems they're encountering. For example, instead of writing the heading "Signals", consider writing "Reacting to changes with signals". The second title makes it clear what the purpose of signals is.

Note

Les longs titres de section entraînent de longues entrées dans le menu latéral, ce qui peut rendre la navigation difficile. Essayez de limiter la longueur des titres à cinq mots ou moins.

If the page assumes specific knowledge of other Godot features, mention it and link to the corresponding documentation. For instance, a page about physics may use signals, in which case you could note that the signals tutorial is a prerequisite. You may also link to other websites for prerequisites beyond the documentation's scope. For example, you could link to an introduction to programming in the getting started guide, or a website that teaches math theory in the math section.

Limiter la charge cognitive

Limitez la charge cognitive nécessaire à la lecture de la documentation. Plus le langage utilisé est simple et explicite, plus l'apprentissage est efficace. Vous pouvez le faire en :

  1. Introduisant un seul concept nouveau à la fois, dans la mesure du possible.

  2. Utilisant un anglais simple, comme nous le recommandons dans nos directives de rédaction.

  3. Including one or more concrete usage examples. Prefer a real-world example to one that uses names like foo, bar, or baz.

While many people may understand more complex language and abstract examples, you will lose others. Understandable writing and practical examples benefit everyone.

Always make an effort to put yourself in the user's shoes. When we understand something thoroughly, it becomes obvious to us. We may fail to think about details relevant to a newcomer, but good documentation meets users where they are. We should explain each feature's capabilities or intended uses with the most straightforward language possible.

Essayez de vous souvenir de ce que vous avez d'abord dû savoir au début de votre apprentissage de cette fonctionnalité ou de ce concept. Quels sont les nouveaux termes que vous avez dû apprendre ? Qu'est-ce qui vous a troublé ? Qu'est-ce qui a été le plus difficile à comprendre ? Vous souhaiterez que les utilisateurs examinent votre travail, et nous vous recommandons de vous entraîner à expliquer la fonctionnalité avant d'écrire à son sujet.

Note

Programming fundamentals are a prerequisite for using a complex engine like Godot. Talking about variables, functions, or classes is acceptable. But we should favor plain language over specific terminology like "metaprogramming". If you need to use precise terms, be sure to define them.