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

Computer graphics is an incredibly interesting field. There are many rules, exceptions to those rules, and interesting details. However, expanding into details can add unnecessary content; therefore, keep the text concise and relevant to the end user.

Mantenible

Keep in mind that Blender has frequent releases, so try to write content that will not have to be redone the moment some small change is made. This also helps a small documentation community maintain the 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.

  • Use American English (e.g: modeling and not modelling, color and not colour) also for formatting numbers (e.g: 2,718.28 and not 2 718,28).

  • Tener cuidado con la gramática, la selección de palabras y el uso de un lenguaje simple.

  • Keep sentences short and clear.

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

Evitar:

  • Avoid writing in the first person perspective, about yourself, or about your own opinions.

  • 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).»

    These details are not useful for users and become quickly outdated.

  • Documentar errores.

    Blender often has hundreds of bugs fixed between releases, so the manual cannot be expected to keep up.

    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.

  • Avoid product placements, e.g. unnecessarily promoting software or hardware brands. Keep content vendor-neutral where possible.

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

  • Avoid listing every option in a menu, such as frame rates.

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

  • Simplemente copiar las mismas descripciones exactas que ya aparecen en 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 resulten ú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
   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.