Guias de estilo de escrita

Objetivos principais

Os principais objetivos para este manual são os seguintes:

Foco no usuário

The manual is written for people educated in computer graphics, who understand the basics of 3D and/or know other 3D software. While some areas of computer graphics are highly technical, this manual shall be kept understandable by non-technical users.

Completo

The manual provides detailed functional description of all features, tools and options in Blender. While there is a canonical source of truth for each of Blender’s key areas, this does not mean we have to document every small detail. The manual should provide information on what a feature is, how to use it, and its purpose. More background information should be provided when necessary to give deeper understanding of a 3D pipeline.

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.

Facilmente mantido

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.

Orientações sobre conteúdo

De maneira a manter um estilo de escrita consistente dentro do manual, por favor, tenha esta página em mente e somente desvie-se dessas orientações quando houver uma boa razão para fazê-lo.

Regras de ouro:

  • A checagem ortográfica é altamente recomendada.

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

  • Tome cuidado com gramática, uso de palavras apropriadas e utilize o Inglês simples.

  • Keep sentences short and clear.

  • Incluir a razão pela qual ou como uma opção funciona e pode ser útil é uma boa ideia.

  • Caso você não tenha certeza de como uma ferramenta ou função é executada, pergunte a alguém ou encontre a pessoa que a desenvolveu para que possa tirar dúvidas.

O que deve ser evitado:

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

  • Evite as chamadas weasel words (palavras vazias ou ser desnecessariamente vago, por exemplo:

    «Recarregar o arquivo irá provavelmente consertar o problema»
    «A maioria das pessoas não utiliza esta opção pois…»

  • Evite incluir detalhes específicos como:

    «O Blender possui 23 diferentes tipos de modificadores.»
    «Habilitar previsões adiciona 65536 bytes ao tamanho de cada arquivo Blender (a menos que seja comprimido).»

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

  • Evite defeitos na documentação.

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

    Issues that 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, e.g. unnecessarily promoting software or hardware brands. Keep content vendor-neutral where possible.

  • Evite explicações técnicas sobre as implementações matemáticas ou algorítmicas de uma funcionalidade caso haja uma maneira simples de explicá-la.

    (Por exemplo, explicar como funcionam os algoritmos de smoothing de malha é desnecessário, mas os blending types de um Mix node precisam de uma explicação matemática.)

  • Evite repetições de grandes partes do texto. Simplesmente explique-o apenas uma vez, e daí em diante use referências para esta explicação.

    Para a terminologia em geral, considere a definição de um :term: dentro do glossário.

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

    Os conteúdos destas áreas podem ser apenas sumarizados ou simplesmente omitidos. - Estes tipos de lista simplesmente estão mostrando o que já é óbvio na interface e acabam sendo muito texto para ser lido e mantido no manual.

  • Evite a documentação de alterações no Blender entre os lançamentos, pois essa é a funcionalidade das «Notas de lançamento». Nossa necessidade é simplesmente documentar o estado atual do Blender.

  • A menos que uma unidade ou valor de medição seja obscuro ou imprevisível, não há necessidade de mencioná-lo.

  • Não faça simples cópias das dicas de ferramentas do Blender. – As pessoas normalmente vêm ao manual para aprender mais do que é fornecido pela interface de usuário.

    Como último recurso, você poderá adicionar comentários (que não serão mostrados na página em HTML, mas serão úteis para outros editores):

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

Glossário

Esta seção é especificamente sobre a seção do Glossário, onde definimos termos comuns no Blender e na computação gráfica.

Regras de ouro:

  • Defina o termo antes de fornecer quaisquer informações futuras.

  • Evite usar construções de frases como «Isto é» ou «xyz é», antes da definição.

  • Evite a repetição do termo imediatamente ou sua reutilização frequente dentro da definição.

  • Evite a adição de termos não encontrados na interface do Blender ou no manual.

  • Evite entradas excessivamente longas. Caso uma explicação de um termo complexo seja necessária, suplemente-o com ligações externas.

  • Evite a duplicação da documentação; Caso a explicação do termo seja o foco principal de uma outra seção do manual (por exemplo, caso o termo seja o nome de uma ferramenta), crie uma simples ligação para esta seção, ou procure evitar inteiramente a criação de mais uma entrada no glossário.

  • As ligações para referências na internet (URLs) devem ser adicionadas no final das páginas, formatadas da seguinte maneira:

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

Examples

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.

Deveria ser escrita dessa maneira, inserindo uma definição inicialmente:

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.

Deveria ser escrita mais aproximadamente dessa maneira, evitando a repetição imediata do termo:

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.

Deveria ser escrita mais aproximadamente dessa maneira, evitando o «isto é»:

Curve
   A line interpolated between Control Vertices.
   Common types include Bézier and NURBS.