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

<=

11.6. Linting com Vale

Para manter clareza e consistência em toda a documentação e páginas do site, estilos Vale foram introduzidos na árvore de documentação. Vale é um linter poderoso para escrever regras personalizadas e pode ser usado em vários cenários. Neste momento o Vale pode ser usado como uma ferramenta de linha de comando, para pipeline de CI/CD e integrado ao editor de sua escolha.

A tabela a seguir descreve os nomes das regras atuais e a respectiva severidade.

NomeSeveridade

BrandTerms

error

ConsciousLanguage

warning

Contractions

suggestions

EOLSpacing

warning

Hang

warning

Hyphens

warning

Repetition

warning

Spacing

error

Spelling

warning

Weasel

warning

11.6.1. Current Vale Rules

  1. BrandTerms: Como o Projeto FreeBSD, todos os principais fornecedores e empresas têm regras específicas para escrever seu nome de marca. de acordo com as regras de Copyright da Fundação FreeBSD, freebsd deve ser escrito como FreeBSD. Da mesma forma, deve-se tomar cuidado para respeitar a escrita da marca de outros e escrever PostgreSQL, Node.js, Let’s Encrypt, etc. Nomes de marcas ausentes devem ser adicionados ao .vale/styles/FreeBSD/BrandTerms.yml " no repositório doc.

  2. Contractions: Palavras contraídas não devem ser usadas. Esta regra evita todas as contrações e sugere palavras completas.

  3. Hang: Hang é freqüentemente usado para transmitir o significado de que o aplicativo parou de responder. Esta norma propõe melhor redação.

  4. Repetition: Muitas vezes, as mesmas palavras são digitadas duas vezes ao sair do teclado e voltar ao trabalho novamente. Esta regra encontra palavras repetidas e avisa os usuários.

  5. Weasel: Esta regra trata de evitar palavras de coloquiais. O uso de palavras coloquiais é controverso, então no momento a lista de palavras está sendo avaliada e o nível de gravidade está marcado como warning. No caso de uma palavra usada ser marcada com frequência como palavra coloquial, ela deve ser removida de .vale/styles/FreeBSD/Weasel.yml" no repositório doc.

  6. ConsciousLanguage: Esta regra propõe usos de linguagens conscientes como evitar as palavras white/black/master/slave - branco/negro/mestre/escravo.

  7. EOLSpacing: Na maioria dos documentos, espaços no fim da linha (EOL) está presente, o que não é a situação desejável.

  8. Hyphens: Muitas vezes advérbios que terminam com 'ly' são adicionados com um hífen, o que está errado.

  9. Spacing: Freqüentemente, os espaços duplos são difíceis de se captar a olho nu, o que é abordado aqui.

  10. Spelling: No momento, há uma mistura de grafias en_US e en_UK na documentação e no site. Um dicionário personalizado Aspell foi adicionado, que usa estritamente en_US e não aceita a variantes en_UK de nenhuma palavra. Ele também possui uma lista de exceções para ignorar os termos específicos do FreeBSD. No momento a lista é básica com o mínimo de palavras apenas como uma prova de conceito, mas se alguma palavra estiver correta e não estiver disponível no dicionário, a palavra deve ser adicionada ao .vale/styles/FreeBSD/spelling-exceptions.txt no repositório doc.

Mais regras serão introduzidas nos próximos dias, quando e onde for necessário.

11.6.2. Utilizando o Vale

O Vale pode ser usado na linha de comando e no editor ou IDE. textproc/vale pode ser instalado da seguinte forma:

$ pkg install vale

11.6.2.1. Usando o Vale na linha de comando

Considerando o fato de que o repositório doc foi clonado em ~/doc" os seguintes comandos são necessários para executar:

% cd ~/doc
% vale .

O Vale é um programa intensivo de CPU e memória devido à natureza do aplicativo e pode demorar um pouco para mostrar qualquer saída na tela. A melhor maneira de executar o aplicativo é em diretórios ou arquivos específicos, em vez de todo o repositório doc, pois isso já é feito na pipeline de CI.

11.6.2.2. Usando Vale em editores

O Vale funciona com os principais editores tradicionais como o editors/vim, editors/emacs, editors/vscode. No momento as configurações necessárias para editors/vim estão descritas em Vim. As configurações necessárias para editors/emacs estão sendo construídas.


Última alteração em: 24 de janeiro de 2023 por Danilo G. Baio