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 12. Estilo de Escrita
Esta tradução pode estar desatualizada. Para ajudar com as traduções, acesse a ferramenta de traduções do FreeBSD.
Índice
12.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 elas.
12.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".
12.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.
12.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.
12.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, devem 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
gitpara atualizar o código fonte.Correto: Use o
gitpara 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
man:[]com a entidade csh(1)):Errado: veja
man cshpara mais informações.Certo: Veja csh(1).
Para mais informações sobre o estilo de escrita, consulte Elements of Style de William Strunk.
12.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.
12.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.
12.5. 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 `.
12.6. 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 | <= | ⇐ |
12.7. 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. Atualmente o Vale pode ser usado como uma ferramenta de linha de comando, para pipelines de CI/CD e integrado a um editor de texto de sua escolha.
A tabela a seguir descreve os nomes das regras atuais e as suas respectivas severidade.
| Nome | Severidade |
|---|---|
FreeBSD.BrandTerms | erro |
FreeBSD.ConsciousLanguage | aviso |
FreeBSD.Contractions | sugestão |
FreeBSD.EOLSpacing | aviso |
FreeBSD.Hang | aviso |
FreeBSD.Hyphens | aviso |
FreeBSD.Spacing | erro |
FreeBSD.SuperfluousOptArgInLinks | sugestão |
Vale.Avoid | erro |
Vale.Repetition | erro |
Vale.Spelling | erro |
Vale.Terms | erro |
12.7.1. Regras Atuais do Vale
FreeBSD.BrandTerms: De acordo com as regras de direitos autorais da Fundação FreeBSD, freebsd deve ser escrito como FreeBSD. Da mesma forma, todos os principais fornecedores e empresas têm regras específicas sobre como escrever seus nomes de marcas e marcas registradas. Deve-se tomar cuidado para respeitar o valor da marca de outras pessoas e reservar um tempo para 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.FreeBSD.ConsciousLanguage: Esta regra propõe o uso de linguagem consciente para que palavras sensíveis apontando para a cor, idade, raça ou orientação sexual das pessoas sejam evitadas sempre que possível.
FreeBSD.Contractions: Palavras contraídas não devem ser usadas. Esta regra evita todas as contrações e sugere palavras completas.
FreeBSD.EOLSpacing: Na maioria dos documentos, espaços presentes no fim da linha (EOL) não são desejáveis.
FreeBSD.Hang:
Hangé frequentemente usado para significar de que o aplicativo parou de responder. Esta norma propõe melhor redação.FreeBSD.Hyphens: Muitas vezes advérbios que terminam com 'ly' são adicionados com um hífen, o que está errado.
FreeBSD.Spacing: Muitas vezes, os espaços duplos são difíceis de captar a olho nu e isso é abordado aqui.
FreeBSD.SuperfluousOptArgInLinks: Sugere colchetes vazios nas macros
link:quando o texto exibido coincide com a URL.Vale.Avoid: Impõe os termos de vocabulário NÃO USE para o Projeto FreeBSD. Se for encontrada alguma palavra que não deva estar na documentação, a palavra deve ser adicionada a .vale/styles/Vocab/Terms/reject.txt no repositório
doc. A lista está vazia no momento.Vale.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.
Vale.Spelling: No momento, há uma mistura de grafias en_US e en_GB na documentação e no site. Vale vem com um dicionário embutido do qual usa estritamente en_US e não aceita a variante en_GB de nenhuma palavra.
Vale.Terms: Aplica os termos de vocabulário PREFERIDO para o Projeto FreeBSD. No momento, a lista de termos está vazia e os termos específicos do FreeBSD serão adicionados gradualmente. Se alguma palavra estiver correta e não disponível no dicionário, a palavra deve ser adicionada ao .vale/styles/Vocab/Terms/accept.txt no repositório
doc.
Mais regras serão introduzidas nos próximos dias, quando e onde for necessário.
12.7.2. Utilizando o Vale
O Vale pode ser usado em linha de comando e em um editor de texto ou IDE. textproc/vale pode ser instalado da seguinte forma:
$ pkg install vale12.7.2.1. Usando o Vale na linha de comando
Assumindo 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. Uma melhor maneira de executar o aplicativo é em diretórios ou arquivos específicos, em vez de todo o repositório |
12.7.2.2. Usando Vale em editores
O Vale funciona com os principais editores tradicionais como o editors/vim, editors/emacs, editors/vscode. No momento a configuração necessária para o editors/vim estão descritas em rossref:editor-config[editor-config-vim, Vim]. As configuração para o editors/emacs está sendo desenvolvida.
Última alteração em: 9 de março de 2024 por Danilo G. Baio