Diretrizes de tom e registo

Muitas pessoas, incluindo profissionais de TI e programadores, leem a documentação do . NET para aprender sobre o .NET e a sua utilização no trabalho. O seu objetivo é criar excelente documentação que ajude os leitores nesta aprendizagem. As nossas diretrizes ajudam-no a atingi-lo. O nosso guia de estilo contém as recomendações apresentadas abaixo.

Utilize um tom conversacional

O parágrafo seguinte está escrito num estilo conversacional. Aquele que se segue tem um estilo mais académico.

Estilo adequado

Queremos que a nossa documentação tenha um tom conversacional. À medida que lê os nossos tutoriais ou explicações, deve sentir que está a ter uma conversa com o autor. A sua experiência deve ser informal, conversacional e informativa. Deve sentir que o autor lhe está a explicar diretamente os conceitos.

Estilo inadequado

É possível observar o contraste entre um estilo conversacional e o estilo que advém de uma abordagem académica a assuntos técnicos. Estes recursos são bastante úteis, mas os autores escreveram-nos com um estilo muito diferente da nossa documentação. As publicações académicas são definidas por um tom e estilo de escrita muito distintos. Isso pode fazer-nos sentir que estamos a ler um texto muito entediante.

Dirija-se ao leitor

O parágrafo seguinte dirige-se ao leitor. Aquele que se segue utiliza um estilo mais distante. Escreva de modo a evitar a distância entre autor e leitor.

Estilo adequado

Escreva os seus artigos como se estivesse a falar diretamente com o leitor. Para isso, dirija-se ao leitor com frequência (como nestas duas frases). Isto não significa necessariamente recorrer à palavra "você". Escreva diretamente para o leitor. Escreva frases no imperativo. Diga ao leitor o que pretende que este aprenda.

Estilo inadequado

Um autor pode optar por escrever para alguém no geral. Neste caso, o autor terá de encontrar um nome ou pronome para se referir ao leitor. O leitor poderá achar este estilo distante e menos agradável de se ler.

Utilize a voz ativa

Escreva os seus artigos na voz ativa. A voz ativa significa que o sujeito da frase realiza a ação (o verbo) da mesma. A voz ativa contrasta com a voz passiva, em que a estrutura da frase indica que a ação recai sobre o sujeito da mesma. Compare estes dois exemplos:

O compilador transformou código-fonte num executável.

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

A primeira frase utiliza a voz ativa. A segunda frase foi escrita na voz passiva. (Estas duas frases também constituem um exemplo de cada estilo.)

Recomendamos a voz ativa, porque facilita a leitura. A voz passiva pode dificultar mais a leitura.

Escreva para leitores que possam ter um vocabulário limitado

Os seus artigos são redigidos para uma audiência internacional. Muitos dos seus leitores não são falantes nativos e podem não ter o seu nível de vocabulário.

No entanto, não se esqueça do facto de estar a escrever para profissionais técnicos. Pode pressupor que os leitores têm conhecimentos de programação e dos termos específicos do vocabulário desta área. Programação Orientada para Objetos, Classe e Objeto, Função e Método serão termos conhecidos. No entanto, nem todos os leitores dos seus artigos terão um curso superior de informática. Termos como "idempotent" terão provavelmente de ser definidos, caso os utilize. Por exemplo:

O método Close() é "idempotent", ou seja, chamá-lo uma só vez terá o mesmo efeito que chamá-lo múltiplas vezes.

Evite os verbos no futuro

O conceito de verbos no futuro não é igual em todos os idiomas. A utilização de verbos no futuro pode dificultar a leitura dos seus documentos. Além disso, ao utilizar um verbo no futuro, permanece a questão de "quando". Se disser que "Aprender a utilizar o PowerShell será útil para si", o leitor pode questionar-se sobre quando será útil. Utilize "Aprender a utilizar o PowerShell é útil para si" em vez da estrutura anterior.

Defina os conceitos em primeiro lugar e dê as explicações depois

Quando apresentar um novo conceito ao leitor, defina-o antes de explicar a sua utilidade. É importante que o leitor compreenda a definição de um conceito em primeiro lugar, para depois poder compreender as suas vantagens ou desvantagens.