Diretrizes de tom e comunicação

Uma ampla variedade de pessoas, incluindo profissionais de TI e desenvolvedores, leem os documentos do .NET para aprender sobre o .NET e para usá-lo no trabalho. Sua meta é criar uma documentação que ajude o leitor em sua jornada. Nossas diretrizes ajudam você a fazer isso. Nosso guia de estilo contém as seguintes recomendações:

Use um tom de conversa

O parágrafo a seguir foi escrito em um tom coloquial. O parágrafo seguinte tem um estilo mais acadêmico.

Estilo adequado

Queremos que nossa documentação tenha um tom de conversa. Você deve se sentir como se estivesse conversando com o autor quando lê nossos tutoriais ou explicações. Para você, a experiência deve ser informal, descontraída e informativa. Os leitores devem se sentir como se estivessem ouvindo o autor explicar os conceitos a eles.

Estilo inadequado

É possível ver a diferença entre um estilo informal e o estilo que é visto em tratamentos mais acadêmicos de tópicos técnicos. Esses recursos são muito úteis, mas os autores escreveram esses artigos com um estilo muito diferente de nossa documentação. Quando uma pessoa lê um periódico acadêmico, ela encontra um tom e um estilo de escrita muito diferente. A sensação é de estar lendo uma descrição muito seca de um tópico muito seco.

Escrever na segunda pessoa

O parágrafo a seguir está escrito na segunda pessoa. O parágrafo seguinte está em terceira pessoa. Escreva na segunda pessoa.

Estilo adequado

Escreva seus artigos como se estivesse falando diretamente com o leitor. Use a segunda pessoa com frequência (como nessas duas frases). Usar a segunda pessoa nem sempre significa usar a palavra “você”. Escreva diretamente para o leitor. Escreva frases no imperativo. Diga ao leitor o que você quer que ele aprenda.

Estilo inadequado

Um autor também pode optar por escrever na terceira pessoa. Nesse modelo, o autor deve encontrar um pronome ou substantivo para usar ao se referir ao leitor. Frequentemente, o leitor pode achar esse estilo com a terceira pessoa menos envolvente e menos agradável de ler.

Usar a voz ativa

Escreva seus artigos em voz ativa. Voz ativa significa que o sujeito da frase realiza a ação (verbo) da frase. Ela é diferente da voz passiva, em que a frase é organizada de forma que o sujeito recebe a ação. Compare estes dois exemplos:

O compilador transformou o código-fonte em um executável.

O código-fonte foi transformado em um executável pelo compilador.

A primeira frase usa a voz ativa. A segunda frase foi escrita na voz passiva. (Essas duas frases fornecem outro exemplo de cada estilo).

Recomendamos a voz ativa porque ela é mais legível. A voz passiva pode ser mais difícil de ler.

Escreva para leitores que talvez tenham um vocabulário limitado

Seus artigos têm um público-alvo internacional. Muitos de seus leitores não são falantes nativos de português e podem não ter o vocabulário que você tem.

No entanto, você ainda está escrevendo para profissionais técnicos. Você pode presumir que seus leitores têm conhecimento de programação e o vocabulário específico com relação a termos de programação. Programação Controlada por Objetos, Classe, Objeto, Função e Método são termos conhecidos. No entanto, nem todos que leem seus artigos têm graduação formal em ciência da computação. Termos como "idempotente" provavelmente precisarão ser definidos se você os usar, por exemplo:

O método Close() é idempotente, o que significa que você pode chamá-lo várias vezes e o efeito será o mesmo do que se você o tivesse chamado apenas uma vez.

Evitar o tempo futuro

Em alguns idiomas que não são o inglês, o conceito de tempo futuro é diferente do inglês. Usar o tempo futuro pode dificultar a leitura dos documentos. Além disso, quando usamos tempo futuro, a pergunta óbvia é “quando?”. Sendo assim, se você disser "Aprender a usar o PowerShell será bom para você", a pergunta óbvia para o leitor será "quando isso será bom?". Em vez disso, diga apenas "Apender o PowerShell é bom para você".

O que é – e daí?

Sempre que apresentar um novo conceito ao leito, defina o conceito e só então explique por que ele é útil. É importante para o leitor compreender o que é uma coisa para que possa entender seus benefícios (ou entender se não há benefícios).