Guia d’estil d’escriptura

Objectius Principals

Els objectius principals per aquest manual s’esmenten a continuació:

Enfocament a la usuària

El manual està escrit per a persones formades en gràfics per ordinador, que entenen els fonaments bàsics del 3D i/o coneixen altres programaris 3D. Tot i que algunes àrees dels gràfics per ordinador són molt tècniques, aquest manual ha de ser comprensible per als usuàries no tècnics.

Complet

El manual proporciona una descripció funcional i detallada de totes les característiques, eines i opcions del Blender. Tot i que hi ha un únic criteri absolut per a cadascuna de les àrees clau del Blender, això no implica que s’hagin de documentar tots els petits detalls. El manual ha de proporcionar informació sobre què és una funció,com utilitzar-la i la seva finalitat. S’ha de proporcionar més informació de fons quan sigui necessari per donar una comprensió més profunda d’un pipeline 3D.

Consisa

Els gràfics generats per ordinador són un camp interessant amb moltes regles, excepcions a les regles i detalls interessants. Ampliar-se als detalls pot afegir contingut innecessari, cal mantenir el text concís i rellevant per al tema en qüestió.

Mantenible

Cal tenir en compte que el Blender té llançaments freqüents, així que proveu d’escriure contingut que no s’haurà de modificar quan es faci algun petit canvi. Això també ajuda a mantenir el manual per una petita comunitat de documentació.

Guies per al contingut

Per tal de mantenir un estil d’escriptura coherent dins del manual, tingueu en compte aquesta pàgina i només us la salteu amb una bona raó per fer-ho.

Regles generals:

  • És recomana molt la correcció ortogràfica.

  • Empreu anglès americà (p.ex: «modeling» i no «modelling», «color» i no «colour») i també pel que fa als formats numèrics (p. ex. : 2,718.28 i no 2 718,28).

  • Tingueu cura de la gramàtica, utilitzant les paraules adequades i amb un anglès senzill.

  • Mantingueu les frases breus i clares, obtenint un text fàcil de llegir, objectiu i concret.

  • És una bona idea incloure el perquè o com pot ser útil una opció.

  • Si no esteu segur de com funciona una funcionalitat, pregunteu-li a algú altre o busqueu qui l’ha desenvolupat i pregunteu-li.

Cal evitar:

  • Eviteu escriure en primera persona, sobre vosaltres mateixos o opinions personals.

  • Eviteu inconcrecions i utilitzar paraules buides de contingut, per exemple:

    «Recarregar el document probablement solucionarà el problema»
    «La majoria de la gent no utilitza aquesta opció perquè`..»

  • Eviteu incloure detalls específics com ara:

    «Blender té 23 tipus de modificadors diferents.»
    «L’activació de les previsualitzacions afegeix 65536 bytes a la mida de cada document del Blender (tret que estigui comprimit)»

    Aquests detalls no són útils per als usuaris per memoritzar i queden ràpidament obsolets.

  • Cal evitar documentar errors.

    Blender sovint té centenars d’errors corregits entre versions, per la qual cosa no és realista fer-ne referència ni tan sols a una mínima part des del manual, mantenint aquesta llista actualitzada.

    Els problemes coneguts per les desenvolupadores i que no es resoldran abans de la propera versió es poden documentar com a limitacions conegudes. En alguns casos, pot ser millor incloure’ls a la secció Resolució de problemes.

  • Cal Evitar fer referencia a productes, és a dir, promocionar innecessàriament marques de programari o maquinari. Cal mantenir un contingut neutral en la mesura del possible.

  • Cal evitar les explicacions tècniques sobre la implementació matemàtica/algorítmica d’una funcionalitat si hi ha una manera més senzilla d’explicar-la.

    (Per exemple, explicar com funcionen els algoritmes de suavització de malla no és necessari, però els tipus de combinació d’un node Mix necessiten una explicació matemàtica.)

  • Cal evitar la repetició de grans porcions de text. Expliqueu-ho una vegada i, a partir d’aleshores, referencieu aquesta explicació.

    Per a la terminologia general, considereu la possibilitat de definir un term: al glossari.

  • Cal evitar enumeracions d’opcions similars, com ara llistar tots els valors predefinits o cada velocitat de fotogrames en un menú de selecció.

    El seu contingut es pot resumir o simplement ometre. –- Aquestes llistes només mostren allò que ja és obvi a la interfície i acaben sent molt text per llegir i mantenir.

  • Cal evitar documentar els canvis que es produexin al Blender entre versions, per això serveixen les notes de la versió. Només necessitem documentar l’estat actual del Blender.

  • A menys que la unitat en què es mesura un valor sigui obscura i impredictible, no cal esmentar-la.

  • No copieu simplement les pistes del Blender. –- La gent recorrerà al manual per aprendre més del que ja es troben a la IU.

    Com a últim recurs, podeu afegir un comentari (que no es mostrarà a la pàgina HTML, però pot ser útil a altres editors):

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

Glossari

Aquesta secció fa referencia al Glossari, on es defineixen termes comuns al Blender i als gràfics generats per ordinador.

Regles generals:

  • Definiu el terme abans de proporcionar qualsevol informació addicional.

  • Cal evitar utilitzar construccions com «és» o «xyz és» abans de la definició.

  • Cal evitar repetir el terme immediatament o utilitzar-lo en la definició.

  • Cal Evitar afegir termes que no es troben a la interfície del Blender o al manual.

  • Cal evitar les entrades massa llargues. Si es necessita una explicació d’un terme complex, complementeu-lo amb enllaços externs.

  • Cal evitar duplicar documentació; si explicar el terme és l’objectiu principal d’una altra secció del manual (p. ex., si el terme és el nom d’una eina), simplement enllaça amb aquesta secció o evita crear una entrada completa al glossari.

  • Les referències d’URL s’han d’afegir al final, amb el format següent, p. ex.:

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

Exemples

Aquesta entrada:

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’escriuria altrament així, posant-hi abans una definició:

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.

Aquesta entrada:

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

S’escriuria així, evitant la repetició immediata del terme:

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

Aquesta entrada:

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

S’escriuria altrament així, evitant el «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.