Guias de estilo de escrita

Objetivos principais

Os principais objetivos para este manual estão explicados abaixo.

Foco no usuário
Mesmo que algumas áreas da computação gráfica sejam altamente técnicas, este manual deve ser mantido de maneira inteligível para usuários não técnicos.
Completo
Portanto, isso deve ser feito de maneira que exista uma fonte canônica fidedigna para cada uma das áreas importantes do Blender. Isto não significa que será necessário que documentemos cada pequeno detalhe, mas os usuários não deverão depender de pesquisas em outros locais para encontrar a finalidade das principais funcionalidades do software.
Conciso
A computação gráfica é um campo incrivelmente interessante, existem muitas regras, exceções as regras e detalhes interessantes. A expansão em detalhes minuciosos pode adicionar conteúdo desnecessário, portanto, mantenha os textos concisos e relevantes ao tópico abordado.
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 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.
  • 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 muitas vezes tem centenas de defeitos (bugs) consertados entre os lançamentos, portanto, não é realístico referenciar nem mesmo uma fração das revisões dos consertos a partir do manual, sendo que essa lista sempre será mantida atualizada.

    Problemas que têm conhecimento dos desenvolvedores e que não serão resolvidos antes do próximo lançamento devem ser documentados como Limitações conhecidas inicialmente. Em alguns casos, pode ser melhor incluí-las na seção sobre resolução de problemas

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

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

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

Exemplos

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.