Guía de Estilo de Escritura

Objetivos Primarios

Los principales objetivos para este manual son los siguientes.

Centrado en el Usuario

Mientras algunas áreas de los gráficos por computadora son altamente técnicos, este manual debería mantenerse comprensible para los usuarios no técnicos.

Completo

La idea es que se disponga de una fuente canónica objetiva para cada área clave de Blender. Esto no significa que tenemos que documentar cada mínimo detalle, pero los usuarios no deberían tener que buscar en alguna otra parte para encontrar el propósito de las características clave.

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 conciso el texto y relevante al tema en discusión.

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 to maintain the manual.

Guías de Contenido

Para mantener un estilo de escritura consistente dentro del manual, por favor tenga esta página en mente y sólo desvíese de él cuando haya una muy buena razón para hacerlo.

Reglas de oro:

  • Spell checking is strongly recommended.

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

  • Cuide la gramática, la selección de palabras y use Inglés simple.

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

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

  • Si no está seguro acerca de cómo funciona una característica, pregunte a alguien más o intente comunicarse con las personas que lo hayan desarrollado y pregúnteles.

Para evitar:

  • Evite escribir en la perspectiva de primera persona, acerca de usted mismo o sus propias opiniones.

  • Avoid weasel words and being unnecessarily vague, e.g:

    «Reloading the file will probably fix the problem»
    «Most people do not use this option because …»

  • Evite incluir detalles específicos tales como:

    «Blender has 23 different kinds of modifiers.»
    «Enabling previews adds 65536 bytes to the size of each blend-file (unless it is compressed).»

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

  • Evite documentar errores.

    Blender often has 100’s of bugs fixed between releases, so it is not realistic to reference even a fraction of them from the manual, while keeping this list up to date.

    Issues which are known to the developers and are not going to be resolved before the next release can be documented as Known Limitations. In some cases, it may be best to include them in the troubleshooting section.

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

  • Avoid technical explanations about the mathematical/algorithmic implementation of a feature if there is a simpler way to explain it.

    (E.g. explaining how mesh smoothing algorithms work is unnecessary, but the blending types of a Mix node do need a mathematical explanation.)

  • Avoid repetition of large portions of text. Simply explain it once, and from then on refer to that explanation.

    Para terminología general, considere definir un :term: (término) en el Glosario.

  • Avoid enumerations of similar options, such as listing every preset or every frame rate in a select menu.

    Their contents may be summarized or simply omitted. – Such lists are only showing what is already obvious in the interface and end up being a lot of text to read and maintain.

  • Evite documentar cambios en Blender entre los lanzamientos, para esto son las notas de lanzamiento. Solamente necesitamos documentar el estado actual de Blender.

  • A menos que un valor esté medido en alguna unidad desconocida o impredecible, no hay necesidad de mencionarlo.

  • Do not simply copy the tooltips from Blender. – People will come to the manual to learn more than is provided by the UI.

    As a last resort you can add comment (which is not shown in the HTML page, but useful for other editors):

    .. TODO, how does this tool work? ask Joe Blogg's.

Glosario

This section is specifically about the Glossary section, where we define common terms in Blender and computer graphics.

Reglas de oro:

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

  • Avoid using constructs such as «it is» or «xyz is» before the definition.

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

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

  • Evite entradas muy largas. Si se necesita una explicación para un término complejo, auxíliese con enlaces externos.

  • Evite duplicar la documentación; si explicar el término es el objetivo primario de otra sección del manual (ej. si el término es el nombre de una herramienta), simplemente enlace con esa sección o evite directamente crear una entrada en el Glosario.

  • URL references are to be added at the end, formatted as follows, e.g:

    See also `OpenGL <https://en.wikipedia.org/wiki/OpenGL>`__ on Wikipedia.

Ejemplos

This entry:

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.

Would be written like this instead, putting a definition first:

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.

This entry:

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

Would be written more like this, avoiding the immediate repetition of the term:

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

This entry:

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

Would be written more like this, avoiding the «it is»:

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