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

  • Artigo

Este início rápido é um breve guia para escrever conteúdo técnico para publicação no Microsoft Learn. Essas diretrizes serão aplicadas se você estiver criando nova documentação ou atualizando uma documentação existente.

Práticas recomendadas:

  • Verifique a ortografia e a gramática em seus artigos, mesmo que seja necessário copiar e colar no Microsoft Word para fazer isso.
  • Use um tom casual e simpático, como se estivesse conversando com outra pessoa frente a frente.
  • Use frases simples. Com frases fáceis de ler, o leitor pode usar rapidamente as orientações compartilhadas.

Use os princípios de tom da Microsoft

Buscamos seguir esses princípios ao escrever conteúdo técnico para Microsoft Learn. Nem sempre conseguimos atingir o objetivo, mas precisamos continuar tentando!

  • Concentre-se na intenção: os clientes têm uma finalidade específica em mente quando consultam nossa documentação. Antes de começar a escrever, determine claramente quem é o cliente e qual tarefa ele ou ela está tentando fazer. Em seguida, escreva seu artigo para ajudar esse cliente específico a realizar essa tarefa específica.
  • Usar palavras comuns: tente usar o idioma natural, as palavras que os clientes usam. Seja menos formal, mas não menos técnico. Forneça exemplos que expliquem os novos conceitos.
  • Escreva de maneira concisa: não use palavras desnecessárias. Seja afirmativo e não use palavras a mais ou muitos adjetivos. Use frases curtas e concisas. Mantenha o foco do artigo. Se uma tarefa tiver um qualificador, coloque-a no início da frase ou parágrafo. Além disso, reduza ao máximo o número de anotações. Quando puder, use uma captura de tela em vez de texto.
  • Facilite a análise do seu artigo: coloque em primeiro lugar as coisas mais importantes. Use seções para dividir procedimentos longos em grupos de etapas mais gerenciáveis. (Procedimentos com mais de 12 etapas provavelmente são muito longos.) Use uma captura de tela para exemplificar.
  • Demonstre empatia: use um tom de apoio no artigo e use o mínimo possível de isenções de responsabilidade. Seja honesto ao destacar as áreas que serão difíceis para os clientes. O artigo deve abordar o que é mais importante para o cliente. Não deve ser estritamente técnico.

Leve em consideração a localização e a tradução de máquina

Nossos artigos técnicos são traduzidos em vários idiomas e alguns são modificados para mercados e geografias específicos. É possível que as pessoas também usem tradução automática na Web para ler os artigos técnicos. Portanto, tenha as seguintes diretrizes em mente ao escrever:

  • Confira se seu artigo está sem erros de gramática, ortografia ou pontuação: isso é algo que devemos fazer em geral. Alguns editores de Markdown (como o MarkdownPad 2.0) têm um corretor ortográfico básico, mas uma boa prática é colar o conteúdo HTML renderizado do artigo no Word, que tem um corretor ortográfico e gramatical mais robusto.
  • Use frases o mais curtas possível: períodos compostos ou cadeias de frases dificultam a tradução. Divida as frases se puder sem ser redundante ou ficar esquisito. Também não queremos artigos escritos em linguagem artificial.
  • Use construção de frases simples e consistente: a consistência é melhor para a tradução. Evite parênteses e apartes, e coloque o sujeito o mais próximo possível da frase. Confira alguns artigos publicados. Se algum artigo tiver um estilo amigável e fácil de ler, use-o como modelo.
  • Use um vocabulário e formatação consistentes: mais uma vez, a consistência é importante. Coloque em maiúscula somente palavras no início da frase ou que sejam substantivo próprio.
  • Inclua "palavras pequenas": palavras que consideramos pequenas e sem importância em inglês porque são entendidas no contexto (como "um", "o", "esse" e "é") são fundamentais para tradução automática. Lembre-se de incluí-las.

Outros problemas de estilo e tom para prestar atenção

  • Não interrompa as etapas com comentários ou apartes.
  • Para etapas que incluem snippets de código, coloque as informações adicionais sobre a etapa no código como comentários. Isso reduz a quantidade de texto que as pessoas precisam ler. As informações importantes são copiadas no projeto de código para lembrar o leitor o que o código está fazendo ao se referir a ele mais tarde.
  • Use a primeira letra da sentença em maiúscula para todos os títulos e cabeçalhos.
  • Use "entrar" e não "logon".
  • Para ver mais diretrizes, confira o Guia de Estilo de Escrita da Microsoft.

Documentação localizada

  • Se você estiver contribuindo para a documentação localizada, consulte as referências de globalização.
  • Para obter diretrizes de localização, informações sobre estilo e uso de linguagem em publicações técnicas e para obter informações sobre formatos de dados específicos do mercado, baixe o guia de estilo no seu idioma.
  • Visite Terminologia da Microsoft para pesquisar terminologia aprovada específica de um produto ou para fazer o download da Coleção de terminologia da Microsoft no seu idioma.
  • Para saber mais sobre a localização, confira "Comunicações globais" no Guia de Estilo de Escrita da Microsoft.

Observação

A maioria das documentações localizadas não oferece a capacidade de editar ou fornecer comentários por meio do GitHub. Para fazer comentários sobre conteúdo localizado, use o formulário https://aka.ms/provide-feedback.