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 the rules, and interesting details. Expanding into details can add unnecessary content, so keep the text concise and relevant to the topic at hand.

Facilmente mantido

Tenha em mente que o Blender possui lançamentos frequentes, portanto, tente escrever conteúdos que não tenham de ser refeitos em momentos que pequenas mudanças são feitas. Isso também ajuda uma pequena comunidade de documentadores a manter o 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 inglês americano (por exemplo: modeling e não modelling, color e não colour) também para formatar números (por exemplo: 2.718,28 e não 2.718,28).

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

  • Mantenha as sentenças curtas e limpas, resultando em textos que são fáceis de ser lidos, objetivos e que vão direto ao ponto.

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

  • Evite escrever em perspectiva de primeira pessoa, sobre você mesmo ou suas opiniões.

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

    Estes detalhes não são úteis para que os usuários os memorizem e se tornam rapidamente desatualizados.

  • Evite defeitos na documentação.

    O Blender tem frequentemente centenas de bugs corrigidos entre lançamentos, por isso não é realista referenciar mesmo uma fração deles do manual, enquanto mantém esta lista atualizada.

    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.

  • Evite a inserção de produtos, ou seja, a promoção desnecessária de marcas de software ou hardware. Mantenha o conteúdo neutro com relação a vendedores onde for possível.

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

  • Evite a enumeração de opções similares, como a listagem de cada uma das predefinições ou cada uma das taxas de quadros em um menu de seleção.

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

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 type of object defined in terms of a line interpolated between Control Vertices.
   Available types of curves include Bézier and NURBS.