Capítulo 14. Estilo de escrita

Índice
14.1. Dicas
14.2. Diretrizes
14.3. Guia de estilo
14.4. Lista de palavras

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

14.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ível. 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.

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

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

All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.