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 mantén el texto conciso y relevante al tema en discusió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 tenga en cuenta esta página y sólo desvíese de la misma cuando tenga una buena razón para hacerlo.

Reglas de oro:

  • Se recomienda fuertemente la verificación ortográfica.

  • Usa el inglés americano (por ejemplo, modeling y no modelling, color y no colour), también para el formato de los números (por ejemplo: 2,718.28 y no 2 718,28).

  • Ten cuidado con la gramática, la selección de palabras y el uso simple del inglés.

  • Mantén las oraciones cortas y claras, resultando en texto que sea fácil de leer, que sea objetivo y que vaya al grano.

  • Incluir por qué o cómo una opción podría ser útil es una buena idea.

  • Si no estás seguro acerca de cómo funciona una característica, pregúntale a alguien más o comunícate con las personas que la hayan desarrollado y pregúntales.

A ser evitado:

  • Evita escribir en la perspectiva de primera persona, acerca de tú mismo o tus propias opiniones.

  • Evita las palabras comadreja y ser innecesariamente confuso, por ejemplo:

    «Recargar el archivo probablemente solucione el problema»
    «La mayoría de las personas no utiliza esta opción porque…»

  • Evita incluir detalles específicos tales como:

    «Blender tiene 23 tipos diferentes de modificadores.»
    «Habilitar las vistas previas agrega 65536 bytes al tamaño de cada archivo blend (a menos que sea comprimido).»

    Estos detalles no son útiles para que los usuarios los memoricen y quedan rápidamente desactualizados.

  • Evita documentar errores.

    Blender a menudo tiene unos 100 errores que son arreglados entre lanzamientos, así que no es realista referenciar siquiera una fracción de ellos desde el manual, mientras se mantiene esta lista actualizada.

    Los problemas que son conocidos por los desarrolladores y que no van a ser solucionados antes del próximo lanzamiento, se pueden documentar como Limitaciones Conocidas. En algunos casos, puede ser mejor incluirlos en la sección solución de problemas.

  • Evita la colocación de productos, es decir, promover innecesariamente software o marcas de hardware. Mantén al vendedor de contenido neutral siempre que sea posible.

  • Evita explicaciones técnicas acerca de la implementación matemática/algorítmica de una característica si es que hay una manera más sencilla para explicarlo.

    (Por ejemplo, explicar cómo funciona el algoritmo de suavizado de mallas es innecesario, pero los tipos de mezcla de un nodo de mezcla necesitan una explicación matemática.)

  • Evita la repetición de grandes porciones de texto. Simplemente explícalo una vez, y a partir de ese momento, haz referencias a dicha explicación.

    Para la terminología general, considera definir un :term: en el glosario.

  • Evita enumerar opciones similares, tales como listar cada valor preestablecido o cada tasa de frames en un menú de selección.

    Sus contenidos pueden ser resumidos o simplemente omitidos. –Tales listas sólo están mostrando lo que ya es obvio en la interfaz y terminan siendo un montón de texto para leer y mantener.

  • Evita documentar cambios en Blender entre los lanzamientos, para esto están las notas de lanzamiento. Solamente necesitamos documentar el estado actual de Blender.

  • A menos que la unidad en la que un valor está medido sea desconocida o impredecible, no hay necesidad de mencionarla.

  • No copies simplemente los tooltips de Blender.– Las personas vendrán al manual para aprender más de lo que es provisto por la interfaz de usuario.

    Como último recurso, puedes 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 de Glosario, donde definimos términos comunes a Blender y a los gráficos computacionales.

Reglas de oro:

  • Define el término antes de proveer cualquier información adicional.

  • Evita usar construcciones tales como «esto es»* o «xyz es» antes de la definición.

  • Evita repetir el término inmediatamente o usarlo en la definición.

  • Evita agregar términos que no se encuentren en la interfaz de Blender o en el manual.

  • Evita entradas muy largas. Si se necesita una explicación para un término complejo, compleméntalo con enlaces externos.

  • Evita 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 es el nombre de una herramienta), simplemente enlaza a esa sección, o evita crear una entrada al Glosario por completo.

  • Las referencias a URLs son agregadas al final, 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 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 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.