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, hay muchas reglas, excepciones a las reglas y detalles interesantes. Expandirse en los detalles podrá llegar a agregar 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 rehecho 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.

Reglas de oro:

  • Se recomienda encarecidamente revisar la ortografía.

  • Use American English (e.g: modeling and not modeling, 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.

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

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.

    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.

  • La referencias a productos, es decir, promover innecesariamente software o marcas de 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 fusión 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.

  • Enumerar opciones similares, tales como el listado de cada preajuste o cada frecuencia de fotogramas en un menú específico.

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