Guide de style d’écriture

Les principaux objectifs

Les objectifs principaux pour ce manuel sont les suivants :

Ciblé sur l’utilisateur
certains domaines de l’infographie sont hautement techniques, ce manuel doit rester compréhensible pour des utilisateurs non techniciens.
Complet
Ainsi il existe une source de vérité canonique pour chaque domaine clé de Blender. Ceci ne signifie pas que nous devons documenter chaque petit détail, mais les utilisateurs ne devraient pas avoir à chercher ailleurs pour trouver la raison d’être des fonctionnalités clés.
Concis
L’infographie est un champ incroyablement intéressant, il y a de nombreuses règles, des exceptions aux règles et des détails intéressants. L’expansion dans les détails peut ajouter du contenu non nécessaire, aussi gardez le texte concis et pertinent pour le sujet traité.
Facile à maintenir
Gardez à l’esprit que Blender a de fréquentes versions, aussi essayez d’écrire du contenu qui ne devra pas être repris après chaque petite modification. Ceci contribue aussi à la maintenance du manuel par une petite communauté de documentateurs.

Recommandations pour le contenu

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

Règles empiriques :

  • La vérification orthographique est fortement recommandée.
  • Utilisez l’anglais américain (ex : modeling et non modelling, color et non colour). Également pour formater les nombres (ex,: 2,718.28 et non 2 718,28).
  • Respectez la grammaire, employez la formulation appropriée et utilisez l’anglais simple.
  • Gardez les phrases courtes et claires ; il en résulte un texte facile à lire, objectif et pertinent.
  • Mentionnez pourquoi ou comment une option pourrait être utile est une bonne idée.
  • Si vous n’êtes pas sûr du mode d’emploi d’une fonction, demandez à quelqu’un d’autre ou recherchez la personne qui l’a développée et posez-lui la question.

À é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, ex :

    « Reloading the file will probably fix the problem »
    « Most people do not use this option because … »

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

    « Blender has 23 different kinds of modifiers. »
    « Enabling previews adds 65536 bytes to the size of each blend-file (unless it is compressed). »

    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 bogues corrigés entre les versions, aussi il n’est pas réaliste d’en faire référence dans le manuel, même d’une fraction d’entre eux, même si cette liste est mise à jour.

    Les problèmes qui sont connus des développeurs et qui ne seront pas résolus avant la prochaine version peuvent être documentés en tant que Limitations connues. Dans certains cas, il serait plus opportun de les inclure dans la section Résolution de problèmes.

  • Éviter le positionnement de produits - càd. en faisant inutilement la promotion de marques de logiciels ou de matériel informatique. Gardez le contenu neutre autant que possible.

  • Éviter les explications techniques au sujet de l’implémentation mathématique/algorithmique d’une fonction s’il y a un moyen plus simple de l’expliquer.

    (par ex. expliquer le fonctionnement des algorithmes de lissage de maillage est inutile, mais les types de mélange d’un node mix a vraiment besoin d’une explication mathématique).

  • Éviter la répétition de larges portions de texte. Expliquez simplement une fois, et à partir de là référez-vous à cette explication.

    Pour la terminologie générale, examinez la définition d’un :terme: dans le glossaire.

  • Évitez l’énumération d’options similaires, telles que le listing de chaque préréglage ou de chaque fréquence de trame dans un menu de sélection.

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

  • Évitez de documenter les modifications dans Blender entre les versions, les notes de versions étant destinées à cela. Nous avons seulement besoin de documenter l’état présent de Blender.

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

  • Ne copiez pas simplement les infobulles de Blender. – les gens vont consulter le manuel pour apprendre plus que ce que l’interface utilisateur montre.

    Comme dernier ressort, vous pouvez ajouter un commentaire (qui n’est pas affiché dans la page HTML, mais utile pour les 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 l’infographie,

Règles empiriques :

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

  • É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 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 le premier focus d’une autre section du manuel (par ex. si le terme est le nom d’un outil), soit faites un lien à cette section, soit évitez de créer entièrement une entrée du glossaire.

  • Les références URL sont à ajouter à la fin, formatées comme suit, par ex.

    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.

Serait plutôt à écrire 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.

Serait plus à écrire comme ceci, en évitant le 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.

Serait plus à écrire 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.