Guía de Estilo de Escritura#

Objetivos Primarios#

Los objetivos principales para este manual son los siguientes:

Enfocado al Usuario: El manual está escrito por personas instruidas en gráficos computacionales, quienes entienden lo básico de 3D y/o conocen otro software 3D. Mientras que algunas áreas de los gráficos computacionales son altamente técnicas, este manual seguirá siendo entendible para los usuarios no técnicos.
Completo: El manual provee descripción funcional detallada de todas las características, herramientas y opciones en Blender. A pesar de que haya una fuente confiable canónica por cada área clave de Blender, esto no significa que tengamos que documentar cada pequeño detalle. El manual debería proveer información acerca de lo que es la característica, cómo usarla y su propósito. Más información contextual debería ser provista cuando sea necesario para dar un mayor entendimiento del pipeline 3D.
Conciso: Los gráficos por computadora son un campo increíblemente interesante, hay muchas reglas, excepciones a las reglas y detalles interesantes. Expandirse en los detalles puede agregar contenido innecesariamente, así que mantenga el texto conciso y relevante para el tema en cuestión.
Mantenible: Ten en cuanta que Blender tiene lanzamientos frecuentes, así que intenta escribir contenido que no tendrá que ser rehecho en el momento en que un pequeño cambio sea realizado. Esto también ayuda a que una comunidad pequeña de documentación pueda mantener el manual.

Guías de contenido#

Para mantener un estilo de escritura consistente dentro del manual, por favor tener en cuenta esta página y desviarse sólo cuando exista una muy buena razón para hacerlo.

Reglas de oro:

Se recomienda encarecidamente revisar la ortografía.
Utilizar un español neutro y con trato impersonal; usar el mismo estándar de separación decimal usado en el programa (es decir, 2,718.28 y no 2.718,28).
Tener cuidado con la gramática, la selección de palabras y el uso de un lenguaje simple.
Mantener las oraciones cortas y claras, resultando en un texto que sea fácil de leer, objetivo y que vaya al grano.
Incluir el por qué o el cómo una opción podrá ser de utilidad es siempre una buena idea.
Si no se está seguro acerca de cómo funciona una característica, consultar a alguien más o comunicarse con las personas que la hayan desarrollado para preguntarles.

A ser evitado:

Evitar escribir con trato de usted/tú, en primera persona o acerca de uno mismo o de sus propias opiniones.
Evitar expresiones vacías y ser innecesariamente vago, por ejemplo:

«Recargar el archivo probablemente solucione el problema»

«La mayoría de las personas no utiliza esta opción porque…»
Evitar incluir detalles específicos tales como:

«Blender tiene 23 tipos diferentes de modificadores.»

«Habilitar las vistas previas agregará 65536 bytes al tamaño de cada archivo .blend (a menos que sea comprimido).»

Carece de utilidad que los usuarios memoricen este tipo de detalles y, además, suelen quedar rápidamente desactualizados.
Evitar documentar errores.

En Blender normalmente se corrigen unos 100 errores entre una versión y otra, por lo que no es realista pretender hacer referencia ni siquiera a una parte de ellos en el manual y pretender mantener esa lista actualizada.

Los problemas conocidos por los desarrolladores y que se sabe que no se resolverán antes de la próxima versión, podrán ser documentados como Limitaciones conocidas. En algunos casos, puede ser mejor incluirlos en la sección Resolución de problemas.
Evitar la colocación de productos, es decir, promover innecesariamente software o marcas de hardware. Mantenerse tan agnóstico como sea posible, con respecto a comercializadores de contenido.
Evitar explicaciones técnicas acerca de la implementación matemática/algorítmica de una característica, si es que existe una manera más sencilla para explicarlo.

(Por ejemplo: Explicar cómo funciona el algoritmo de suavizado de mallas es innecesario, pero los modos de fusión del nodo Mezclar sí necesitan una explicación matemática.)
Evitar la repetición de grandes porciones de texto. Explicar simplemente una vez y, a partir de ese momento, hacer referencia a dicha explicación.

Para la terminología general, considerar la definición de un término (:term:) en el glosario.
Evitar enumerar opciones similares, tales como listar cada ajuste preestablecido o cada frecuencia de fotogramas en un menú específico.

Su contenido podrá ser resumido o simplemente omitido. –Tales listas sólo estarán mostrando lo que ya es obvio en la interfaz y terminarán siendo un montón de texto, tanto para quien lee como para quién deba mantenerlo actualizado.
Evitar documentar progresivamente los cambios producidos en Blender de una versión a otra, para esto existen las notas de lanzamiento. Solamente será necesario documentar el estado actual de Blender.
A menos que la unidad en la que un valor es medido sea desconocida o impredecible, no habrá necesidad de mencionarla.
No copiar simplemente las mismas descripciones exactas de Blender.– Las personas vendrán al manual para aprender algo más de lo que provee la propia interfaz.

Como último recurso, será posible agregar comentarios (que no sean mostrados en la página HTML, pero que sean útiles para otros editores):
```
.. TODO, how does this tool work? ask Joe Blogg's.
```

Glosario#

Esta sección es específicamente acerca del Glosario, donde se definen los términos comunes usados en Blender y los gráficos computacionales en general.

Reglas de oro:

Definir el término antes de proveer cualquier información adicional.
Evitar usar construcciones tales como «Esto es», «Se trata de» o «XYZ es»* antes de la definición.
Evitar repetir el término inmediatamente o usarlo en la definición.
Evitar agregar términos que no se encuentren en uso en la interfaz de Blender o en el manual.
Evitar textos muy largos. Si se necesitara una explicación para un término complejo, complementarlo con enlaces externos.
Evitar duplicar la documentación; si explicar el término es el objetivo principal de otra sección del manual (por ejemplo, si el término fuera el nombre de una herramienta), simplemente enlazar a esa sección, o evitar por completo crear una entrada en el Glosario.
Las referencias a URLs serán agregadas al final y formateadas de la siguiente manera:
```
See also `OpenGL <https://en.wikipedia.org/wiki/OpenGL>`__ on Wikipedia.
```

Ejemplos#

Esta 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.

Se podría escribir de esta manera, colocando primero una definición:

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.

Esta entrada:

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

Se podría escribir mejor de esta manera, evitando la repetición inmediata del término:

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

Esta entrada:

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

Se podría escribir mejor de esta manera, evitando el «esto es»:

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