Guide de style d’écriture

Les principaux objectifs

Les principaux objectifs de ce manuel sont les suivants :

Ciblé sur l’utilisateur

Le manuel est écrit pour des personnes formées en infographie, qui comprennent les bases du 3D et/ou connaissent d’autres logiciels 3D. Bien que certains domaines d’infographie soient très techniques, ce manuel doit rester compréhensible par des utilisateurs non techniciens.

Complet

Ce manuel offre une description détaillée de toutes les fonctionnalités, outils et options de Blender. Bien qu’il existe une source de vérité canonique pour chacun des domaines clés de Blender, cela ne signifie pas que nous devons documenter chaque petit détail. Le manuel doit fournir des informations sur ce qu’est une fonctionnalité, comment l’utiliser et son objectif. Des informations de fond supplémentaires doivent être fournies si nécessaire pour permettre une meilleure compréhension d’un pipeline 3D.

Concis

L’infographie est un domaine incroyablement intéressant, il existe de nombreuses règles, des exceptions aux règles et des détails intéressants. Le fait d’entrer dans les détails peut ajouter du contenu inutile, il faut donc que le texte soit concis et pertinent par rapport au sujet traité.

Facile à maintenir

Gardez à l’esprit que Blender sort fréquemment des versions, alors essayez d’écrire un contenu qui n’aura pas à être repris après chaque petite modification. Cela permet également à une petite communauté de documentation de maintenir le manuel.

Recommandations pour le contenu

Afin de maintenir un style d’écriture cohérent dans le manuel, veuillez garder à l’esprit cette page et ne vous en écarter que si vous avez une bonne raison de le faire.

Règles de base :

  • La vérification de l’orthographe est fortement recommandée.

  • Utilisez l’anglais américain (ex : modeling et non modelling, color et non colour), également pour le formatage des nombres (ex : 2,718.28 et non 2 718,28).

  • Faites attention à la grammaire, à la formulation appropriée et utilisez un anglais simple.

  • Faites des phrases courtes et claires, afin d’obtenir un texte facile à lire, objectif et pertinent.

  • Il est bon d’indiquer pourquoi ou comment une option peut être utile.

  • Si vous n’êtes pas sûr du fonctionnement d’une fonctionnalité, demandez à quelqu’un d’autre ou trouvez qui l’a développée et interrogez-le.

À éviter :

  • Évitez d’écrire à la première personne, à propos de vous-même ou de vos propres opinions.

  • Évitez les mots ambigus et inutilement vagues, par exemple :

    “Le rechargement du fichier résoudra probablement le problème”
    “La plupart des gens n’utilisent pas cette option parce que …”

  • Évitez de donner des détails spécifiques tels que :

    “Blender a 23 types de modificateurs différents.”
    “L’activation des aperçus ajoute 65536 octets à la taille de chaque fichier blend (sauf s’il est compressé).”

    Ces détails ne sont pas utiles à mémoriser pour les utilisateurs et ils deviennent rapidement obsolètes.

  • Évitez de documenter les bogues.

    Blender a souvent des centaines de bugs corrigés entre les versions, il n’est donc pas réaliste d’en citer ne serait-ce qu’une fraction dans le manuel, tout en gardant cette liste à jour.

    Les problèmes connus des développeurs et qui ne seront pas résolus avant la prochaine version peuvent être documentés en tant que Known Limitations (Limitations connues). Dans certains cas, il peut être préférable de les inclure dans la section troubleshooting.

  • Évitez le placement de produits, c’est-à-dire promouvoir inutilement des marques de logiciels ou de matériel. Dans la mesure du possible, veillez à ce que le contenu soit neutre par rapport aux fournisseurs.

  • Évitez les explications techniques sur la mise en œuvre mathématique/algorithmique d’une fonctionnalité s’il existe une façon plus simple de l’expliquer.

    (Par exemple, expliquer comment fonctionnent les algorithmes de lissage de maillage est inutile, mais les types de mélange d’un nœud Mix ont vraiment besoin d’une explication mathématique.)

  • Évitez de répéter de grandes portions de texte. Il suffit de l’expliquer une fois, et de se référer à cette explication à partir de ce moment.

    Pour la terminologie générale, pensez à définir un :term: dans le glossaire.

  • Évitez d’énumérer des options similaires, telles que la liste de chaque préréglage ou de chaque fréquence de trames dans un menu de sélection.

    Leur contenu peut être résumé ou simplement omis. – De telles listes ne font que montrer ce qui est déjà évident dans l’interface et finissent par représenter beaucoup de texte à lire et à maintenir.

  • Évitez de documenter les changements dans Blender entre les versions, c’est à cela que servent les notes de version. Il suffit de documenter l’état actuel de Blender.

  • À moins que l’unité dans laquelle une valeur est indiquée soit obscure et imprévisible, il n’y a pas besoin de la mentionner.

  • Ne vous contentez pas de copier les infobulles de Blender. – Les gens viendront au manuel pour en apprendre plus que ce qui est fourni par l’interface utilisateur.

    En dernier recours, vous pouvez ajouter un commentaire (qui n’apparaît pas dans la page HTML, mais qui est utile aux autres éditeurs) :

    .. TODO, how does this tool work? ask Joe Blogg's.

Glossaire

Cette section concerne spécifiquement la section Glossaire, où nous définissons des termes communs dans Blender et dans l’infographie.

Règles de base :

  • Définissez le terme avant de fournir toute autre information.

  • Éviter d’utiliser des expressions telles que “it is” ou “xyz is” avant la définition.

  • Évitez de répéter le terme immédiatement ou l’utiliser dans la définition.

  • Évitez d’ajouter des termes ne se trouvant pas dans l’interface de Blender ou dans le manuel.

  • Évitez des entrées excessivement longues. Si une explication d’un terme complexe est nécessaire, complétez avec des liens externes.

  • Évitez de dupliquer la documentation ; si l’explication du terme est l’objet principal d’une autre section du manuel (par exemple si le terme est le nom d’un outil), il suffit de créer un lien vers cette section, ou évitez absolument de créer une entrée de glossaire.

  • Les références URL doivent être ajoutées à la fin, formatées comme suit, par exemple :

    See also `OpenGL <https://en.wikipedia.org/wiki/OpenGL>`__ on Wikipedia.

Exemples

Cette entrée :

Displacement Mapping
   Uses a grayscale heightmap, like Bump Mapping,
   but the image is used to physically move the vertices of the mesh at render time.
   This is of course only useful if the mesh has large amounts of vertices.

S’écrirait plutôt comme ceci, en mettant d’abord une définition :

Displacement Mapping
   A method for distorting vertices based on an image.
   Similar to Bump Mapping, but instead operates on the mesh's actual geometry.
   This relies on the mesh having enough geometry.

Cette entrée :

Doppler Effect
   The Doppler effect is the change in pitch that occurs
   when a sound has a velocity relative to the listener.

S’écrirait plutôt comme ceci, en évitant la répétition immédiate du terme :

Doppler Effect
   Perceived change in pitch that occurs
   when the source of a sound is moving relative to the listener.

Cette entrée :

Curve
   It is a class of objects.
   In Blender there are Bézier curves and NURBS curves.

S’écrirait plutôt comme ceci, en évitant le “it is” :

Curve
   A type of object defined in terms of a line interpolated between Control Vertices.
   Available types of curves include Bézier and NURBS.