Capítulo 11. Estilo de Escrita

11.1. Dicas

A documentação técnica pode ser melhorada pelo uso consistente de vários princípios. A maioria destes pode ser classificada em três objetivos: ser claro, ser completo e ser conciso. Essas metas podem entrar em conflito umas com as outras. Uma boa escrita consiste em um equilíbrio entre eles.

11.1.1. Seja claro

A clareza é extremamente importante. O leitor pode ser um novato ou ler o documento em um segundo idioma. Esforce-se por um texto simples e descomplicado que explique claramente os conceitos.

Evite discurso florido ou embelezado, piadas ou expressões coloquiais. Escreva da maneira mais simples e clara possível. Um texto simples é mais fácil de se entender e de se traduzir.

Mantenha as explicações o mais curtas, simples e claras possíveis. Evite frases vazias como "a fim de" as quais normalmente significam apenas um "para". Evite palavras potencialmente paternalistas tais como "basicamente". Evite termos latinos como "i.e." ou "cf.", os quais podem ser desconhecidos fora de grupos acadêmicos ou científicos.

Escreva em um estilo formal. Evite dirigir-se ao leitor como "você". Por exemplo, digamos "copie o arquivo para /tmp" em vez de "você pode copiar o arquivo para /tmp".

Dê exemplos claros, corretos, e testados. Um exemplo trivial é melhor do que nenhum exemplo. Um bom exemplo é ainda melhor. Não dê exemplos ruins, identificáveis por desculpas ou frases como "mas realmente isso nunca deve ser feito dessa forma". Exemplos ruins são piores que nenhum exemplo. Dê bons exemplos, porque mesmo quando avisado para não usar o exemplo como mostrado , o leitor normalmente só usa o exemplo como mostrado.

Evite palavras vazias como "deveria", "poderia", "tentaria", ou "podia". Estas palavras implicam que o autor não tem certeza dos fatos e cria dúvidas no leitor.

Da mesma forma, dê instruções como comandos imperativos: não utilize "você deve fazer isso", mas apenas "faça isso".

11.1.2. Seja completo

Não faça suposições sobre as habilidades do leitor. Diga-lhes o que precisam saber. Dê links para outros documentos para fornecer informações básicas sem precisar recriá-las. Coloque-se no lugar do leitor, antecipe as perguntas que eles farão e responda-os.

11.1.3. Seja conciso

Embora as funcionalidades devam ser documentadas completamente, às vezes existe tanta informação que o leitor não consegue encontrar facilmente os detalhes específicos de que necessita. O equilíbrio entre ser completo e ser conciso é um desafio. Uma abordagem é ter uma introdução e, em seguida, uma seção de "início rápido" que descreve a situação mais comum, seguida por uma seção de referência aprofundada.

11.2. Diretrizes

Para promover a consistência entre os inúmeros autores da documentação do FreeBSD, algumas diretrizes foram elaboradas para os autores seguirem.

Use a Ortografia do Inglês Americano

Existem várias variantes do Inglês, com grafias diferentes para a mesma palavra. Onde as grafias diferem, use a variante do Inglês Americano. "color", não "colour", "rationalize", não "rationalise", e assim por diante.

O uso do Inglês Britânico pode ser aceito no caso de um artigo contribuído, no entanto, a ortografia deve ser consistente em todo o documento. Os outros documentos, como livros, site, páginas de manual, etc., terão que usar o Inglês Americano.

Não use contrações

Não use contrações. Sempre soletre a frase na íntegra. "Do not" é a forma correta, "Don’t" é a errada.

Evitar contrações contribui para um tom mais formal, é mais preciso e é um pouco mais fácil para os tradutores.

Use a vírgula serial

Em uma lista de itens dentro de um parágrafo, separe cada item dos outros com uma vírgula. Separe o último item dos outros com uma vírgula e a letra "e".

Por exemplo:

Esta é uma lista de um, dois e três itens.

Esta é uma lista de três itens, "um", "dois", e "três", ou uma lista de dois itens, "um" e "dois" e "três"?

É melhor ser explícito e incluir uma vírgula serial:

Esta é uma lista de um, dois, e três itens.

Evite frases redundantes

Não use frases redundantes. Em particular, "the command", "the file", e "man command" são frequentemente redundantes.

Por exemplo, comandos:

Errado: Use o comando git para atualizar o código fonte.

Correto: Use o git para atualizar o código fonte.

Nomes de arquivo:

Errado: …​ no nome do arquivo /etc/rc.local…​

Correto: …​ no /etc/rc.local…​

Referências de páginas de manual (o segundo exemplo usa citerefentry com a entidade csh(1)):.

Errado: veja man csh para mais informações.

Certo: Veja csh(1).

Para mais informações sobre o estilo de escrita, consulte Elements of Style, de William Strunk.

11.3. Guia de estilo

Para manter o código fonte da documentação consistente quando muitas pessoas diferentes a estiverem editando, siga estas convenções de estilo.

11.4. Uma frase por linha

Use quebras de linha semântica na documentação, uma técnica chamada "uma frase por linha". A ideia dessa técnica é ajudar os usuários a escrever e ler a documentação. Para obter mais informações sobre essa técnica, leia a página Semantic Line Breaks.

Este é um exemplo que não usa "uma frase por linha".

All human beings are born free and equal in dignity and rights. They are endowed with reason and conscience and should act towards one another in a spirit of brotherhood.

E este é um exemplo que usa a técnica.

All human beings are born free and equal in dignity and rights.
They are endowed with reason and conscience and should act towards one another in a spirit of brotherhood.

11.4.1. Siglas

As siglas devem ser definidas na primeira vez que aparecerem em um documento, como em: "Network Time Protocol (NTP)". Depois que o acrônimo tiver sido definido, use apenas a sigla, a menos que faça mais sentido contextualmente usar todo o termo. Siglas geralmente são definidos apenas uma vez por capítulo ou por documento.

Todas as siglas devem ser incluídas com o caractere `.

11.5. Lista de Caracteres Especiais

Esta lista de caracteres especiais mostra a sintaxe correta e a saída quando usada na documentação do FreeBSD. Se um caractere não está nesta lista, pergunte sobre ele na lista de discussão do projeto de documentação do FreeBSD.

NomeSintaxeRenderizado

Copyright

(C)

©

Registrado

(R)

®

Marca Comercial

(TM)

Travessão

--

 — 

Elipses

...

…​

Seta simples para a direita

->

Seta dupla para a direita

=>

Seta simples para a esquerda

<-

Seta dupla para a esquerda

<=


Última alteração em: 6 de fevereiro de 2022 por Danilo G. Baio