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
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¶
In order to maintain a consistent writing style within the manual, please keep this page in mind and only deviate from it when you have a good reason to do so. If in doubt, check with the documentation team on Blender Chat.
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.
RST files should wrap at column 120. No lines of text should exceed that length.
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.
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.
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.
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.
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.