Guía de estilo de escritura¶

Objetivos principales¶

Los objetivos principales para este manual son los siguientes:

Enfocado al usuario: El manual estará escrito para personas instruidas en gráficos computacionales, quienes entiendan lo básico de 3D y/o conozcan otro software 3D. Si bien algunas áreas de los gráficos computacionales son altamente técnicas, este manual deberá seguir siendo entendible para usuarios no técnicos.
Completo: El manual proveerá una descripción funcional detallada de todas las características, herramientas y opciones en Blender. A pesar de que exista una fuente canónica confiable por cada área clave de Blender, esto no significará 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. Cuando fuera necesario deberá proveerse información adicional para dar un mayor entendimiento de una cierta forma de trabajo en 3D.
Conciso: Los gráficos por computadora son un campo increíblemente interesante. Existen muchas reglas, excepciones a las mismas y otros detalles interesantes. Sin embargo, explayarse acerca de esos detalles podría llegar a aumentar el contenido de forma innecesaria, por lo que se recomienda mantener los textos concisos y relevantes para el tema que se esté abordando.
Mantenible: Tener en cuenta que se realizan lanzamientos frecuentes de Blender, por lo que se recomienda escribir contenido que no tenga que ser reescrito en el momento en que un pequeño cambio sea realizado. Esto también ayudará a que una comunidad de documentación de tamaño reducido 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. En caso de duda, recurrir a la asistencia del equipo de documentación en el Blender Chat.

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 frases cortas y claras.
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.
Los archivos RST deben tener un salto de línea en la columna 120. Ninguna línea de texto debería exceder esa longitud.

Evitar:

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

«Recargar el archivo probablemente solucionará el problema»

«La mayoría de las personas no utiliza esta opción porque…»
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).»

Este tipo de detalle carece de utilidad para los usuarios y, además, suele quedar rápidamente desactualizado.
Documentar errores.

Normalmente Blender tiene cientos de correcciones de errores de una versión a la siguiente, por lo que no se espera que el manual las contemple todas.

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.
Deberán evitarse las referencias a productos, es decir, promover innecesariamente marcas de software o hardware. Mantenerse tan agnóstico como sea posible, con respecto a comercializadores de contenido.
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 fundido del nodo Mezclar sí necesitan una explicación matemática.)
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 listar cada opción de un menú, tal como velocidades de fotograma.

Dicho 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 innecesario, tanto para quien lee como para quién deba mantenerlo actualizado.
Documentar progresivamente los cambios producidos en Blender de una versión a otra, para esto existen las notas de lanzamiento y se encuentran disponibles los manuales de las versiones anteriores del programa. Solamente será necesario documentar el estado actual de Blender.
A menos que el tipo de unidad en que un valor es medido sea de difícil presunción o impredecible, no habrá necesidad de mencionarla.
No copiar simplemente las mismas descripciones que aparecen en Blender.

La gente acudirá al manual para aprender más de lo que ya proporciona la propia interfaz del programa. Como último recurso, será posible agregar comentarios (que no serán mostrados en la página HTML, pero que puedan resultar útiles para otros editores):
```
.. TODO how does this tool work? ask Joe Blogg.
```

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
   Distorts vertices with an image.
   Similar to Bump Mapping, but operates on the mesh's geometry.
   The mesh must have 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 line interpolated between Control Vertices.
   Common types include Bézier and NURBS.