Início rápido de estilo e voz do Microsoft Learn

Este início rápido é um breve guia para escrever conteúdo técnico para publicação no Microsoft Learn. Estas diretrizes aplicam-se sempre que cria nova documentação ou atualiza a existente.

Melhores práticas:

  • Verificar a ortografia e gramática dos seus artigos, mesmo que tenha de copiar e colar o texto no Microsoft Word para o fazer.
  • Utilizar um tom informal e amigável, como se estivesse a falar diretamente com outra pessoa.
  • Utilizar frases simples. Criar frases de leitura fácil para que o leitor possa utilizar rapidamente as orientações que partilhar.

Utilizar os princípios da voz da Microsoft

Aspiramos a seguir estes princípios quando escrevemos conteúdo técnico para o Microsoft Learn. Podemos nem sempre consegui-lo, mas vamos continuar a tentar!

  • Foco na intenção: os clientes têm um objetivo específico em mente quando consultam a nossa documentação. Antes de começar a escrever, determine de forma clara quem é o cliente e que tarefa está a tentar realizar. De seguida, escreva o seu artigo para ajudar esse cliente específico a realizar essa tarefa específica.
  • Utilize palavras correntes: experimente utilizar uma linguagem natural, as palavras que os seus clientes utilizam. Seja menos formal, mas sem perder a vertente técnica. Dê exemplos que expliquem os novos conceitos.
  • Escreva de forma concisa: seja direto. Seja afirmativo e não acrescente palavras ou muitos qualificativos. Mantenha as frases curtas e concisas. Mantenha o seu artigo focado. Se uma tarefa tiver um qualificativo, coloque-o no início da frase ou do parágrafo. De igual forma, reduza ao máximo o número de notas utilizadas. Utilize uma captura de ecrã quando não consegue ser conciso no texto.
  • Torne os seus artigos fáceis de digitalizar: coloque o mais importante no início. Utilize secções para colocar partes de procedimentos longos em grupos de passos mais fáceis de gerir. (Procedimentos com mais de 12 etapas são provavelmente muito longos.) Use uma captura de tela quando ela adicionar clareza.
  • Demonstre empatia: utilize um tom prestável no artigo e reduza ao máximo o número de isenções de responsabilidade utilizadas. Seja direto e referencie as áreas que serão mais frustrantes para os clientes. Garanta que os artigos se focam naquilo que importa aos clientes, não faça apenas uma exposição técnica.

Considere a localização e a tradução automática

Os nossos artigos técnicos são traduzidos em vários idiomas e alguns são modificados para geografias ou mercados específicos. As pessoas também podem utilizar a tradução automática na Internet para ler os artigos técnicos. Assim, tenha em atenção as seguintes diretrizes durante a escrita:

  • Verifique se o artigo não contém erros de gramática, ortografia ou pontuação: isto é algo que devemos fazer em geral. Alguns editores de Markdown, como o MarkdownPad 2.0, possuem um corretor ortográfico básico, mas é uma boa prática colar o conteúdo HTML composto do artigo no Word, que tem um corretor ortográfico e gramatical mais robusto.
  • Torne as suas frases o mais curtas possíveis: frases compostas ou conjuntos de orações dificultam a tradução. Divida as frases caso o consiga fazer sem que fiquem muito redundantes ou estranhas. Não queremos artigos escritos de forma não natural.
  • Utilize construções simples e consistentes: a consistência é melhor para a tradução. Evite parênteses e apartes, coloque o sujeito o mais próximo possível do início da frase. Consulte alguns artigos publicados. Se um artigo tiver um estilo amigável e fácil de ler, utilize-o como modelo.
  • Utilize uma redação e a utilização de maiúsculas/minúsculas de forma consistente: novamente, a consistência é fundamental. Não coloque uma palavra em maiúsculas se esta não estiver no início de uma frase ou se não for um nome próprio.
  • Inclua as "palavras pequenas": palavras que consideramos pequenas e sem importância em português pois são compreensíveis dentro do contexto (como "um", "o", "esse" e "é") são fundamentais para a tradução automática. Assegure-se de que as inclui.

Outros problemas de estilo e voz a estar atento

  • Não divida os passos com comentários ou apartes.
  • Nos passos que incluem fragmentos de código, forneça informações adicionais sobre o passo no código como comentários. Desta forma, reduz a quantidade de texto que as pessoas têm de ler. A informação principal é copiada para o projeto de código para lembrar às pessoas do objetivo do código quando o consultarem posteriormente.
  • Utilize iniciais maiúsculas para todos os títulos e cabeçalhos.
  • Utilize "iniciar sessão" e não "ligar-se".
  • Para obter mais diretrizes, veja o Microsoft Writing Style Guide (Guia de Estilo de Escrita da Microsoft).

Documentação localizada

Nota

A maioria da documentação localizada não oferece a capacidade de editar ou fornecer feedback através do GitHub. Para fornecer comentários sobre o conteúdo localizado, use o https://aka.ms/provide-feedback formulário.

  • Last updated on