Directives relatives au contenu¶
Ce document est là pour nous aider à évaluer ce que nous devons inclure dans la documentation officielle. Vous trouverez ci-dessous quelques principes et recommandations pour rédiger un contenu accessible.
Nous visons deux objectifs :
Faites preuve d'empathie envers nos utilisateurs. Nous devons écrire d'une manière qui leur permette d'apprendre facilement à partir des documents.
Écrire un manuel de référence complet. Notre objectif ici n'est pas d'enseigner les bases de la programmation. Au lieu de cela, nous devons fournir une référence sur la façon dont les fonctionnalités de Godot fonctionnent.
Lignes directrices et principes¶
Vous trouverez ci-dessous les lignes directrices que nous devons nous efforcer de suivre. Il ne s'agit cependant pas de règles strictes : exceptionnellement, un sujet nécessitera d'enfreindre une ou plusieurs de ces règles. Néanmoins, nous devons nous efforcer d'atteindre les deux objectifs énumérés ci-dessus.
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.
Faites de votre mieux pour que les documents ** fassent moins de 1000 mots**. Si une page dépasse ce seuil, envisagez de la diviser en deux parties si possible. Limiter la taille des pages nous oblige à écrire de manière concise et à diviser les gros documents pour qu'ils se concentrent chacun sur un problème particulier.
Indiquez clairement à quel problème chaque page ou section de page s'attaque et ce que l'utilisateur en tirera. Les utilisateurs ont besoin de savoir s’ils lisent le bon guide pour résoudre les problèmes qu’ils rencontrent. Par exemple, au lieu d'écrire le titre "Signaux", envisagez d'écrire "Réagir aux changements avec des signaux". Le deuxième titre indique clairement l'objectif des signaux.
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.
Si la page suppose une connaissance spécifique d'autres fonctionnalités de Godot, mentionnez-le et liez-la à la documentation correspondante. Par exemple, une page sur la physique peut utiliser les signaux, auquel cas nous pourrions noter que la page qui présente les signaux est un prérequis.
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 :
Introduisant un seul concept nouveau à la fois, dans la mesure du possible.
Utilisant un anglais simple, comme nous le recommandons dans nos directives de rédaction.
Incluant un ou plusieurs exemples concrets d'utilisation. Préférez un exemple concret à un code abstrait comme
foobar.
Si de nombreuses personnes peuvent comprendre un langage plus complexe et des exemples abstraits, vous en perdrez d'autres. Aussi, une écriture compréhensible et des exemples pratiques profitent à tous.
Faites toujours l'effort de vous mettre à la place de l'utilisateur. Lorsque nous comprenons quelque chose de manière approfondie, cela devient évident pour nous. Nous pouvons ne pas penser aux détails pertinents pour un nouveau venu, mais une bonne documentation rencontre les utilisateurs là où ils sont. Nous devons nous efforcer d’expliquer les capacités ou les utilisations prévues de chaque fonctionnalité avec le langage le plus simple 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
Avoir des bases de programmation est un pré-requis pour utiliser un moteur complexe comme Godot. Parler de variables, de fonctions ou de classes est acceptable. Mais il faut privilégier un langage simple plutôt qu'une terminologie spécifique comme "métaprogrammation". Si vous devez utiliser des termes précis, veillez à les définir.
Lorsqu'une page suppose la connaissance d'une autre fonctionnalité du moteur, déclarez-la au début et créez un lien vers des ressources qui couvrent les besoins des utilisateurs. Vous pouvez également créer un lien vers d'autres sites Web pour les prérequis au-delà de la portée de la documentation. Par exemple, vous pouvez créer un lien vers une introduction à la programmation dans le guide de démarrage ou vers un site Web qui enseigne la théorie des mathématiques dans la section mathématiques.