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.
Capítulo 11. Estilo de Escrita
Índice
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".
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.
Nome | Sintaxe | Renderizado |
---|---|---|
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