Diretrizes de formatação de texto

A utilização consistente e adequada dos estilos negrito, itálico e código em elementos de texto melhora a legibilidade e ajuda a evitar confusões. Se um elemento de formatação de texto não for abrangido por estas orientações, consulte o Guia de Estilo de Escrita da Microsoft. Os seguintes artigos fornecem orientações detalhadas sobre formatação de texto:

• Formatação de elementos de texto comuns

• Formatação de texto em instruções

• Formatando elementos comuns utilizados pelos desenvolvedores

Elementos da IU

Os elementos da interface do usuário, como itens de menu, nomes de caixas de diálogo e nomes de caixas de texto, devem estar em negrito.

• Isto: No Gerenciador de Soluções, clique com o botão direito do mouse no nó do projeto e selecione Adicionar>Novo Item.

• Não é isso: no Gerenciador de Soluções, clique com o botão direito do mouse no nó do projeto e selecione Adicionar > Novo Item.

Nomes de repositórios e ramificações do Git

Use texto em negrito para nomes de repositórios ou ramificações do Git quando selecionado ou inserido nas instruções.

• Isto: No menu de ramificação, selecione principal.

• Não é isso: no menu de ramificação, selecione "principal".

Introduções de novos termos

Use texto em itálico para introduzir um novo termo, juntamente com uma definição ou explicação. Coloque o novo termo em itálico na primeira vez que o utilizar e, em seguida, utilize texto normal para a definição ou explicação.

• Faça isto: no Serviço de Aplicações, as aplicações são executadas num plano do Serviço de Aplicações. Os planos do Serviços de Aplicações definem um conjunto de recursos de computação para a execução de aplicações Web.

• Não é isso: no Serviço de Aplicativo, um aplicativo é executado em um "Plano do Serviço de Aplicativo". Um plano do Serviço de Aplicativo define um conjunto de recursos de computação para execução de um aplicativo Web.

Estilo de código

Utilize-o para:

• Elementos de código, tais como nomes de métodos, nomes de propriedades e palavras-chave de idiomas.
• Comandos de SQL
• Nomes de pacotes NuGet
• Comandos de linha de comando*
• Nomes de tabelas e colunas de bases de dados
• Nomes de recursos que não devem ser traduzidos (por ex., nomes de máquinas virtuais)
• URLs que não pretende que sejam clicáveis

Porquê? Alguns guias de estilo especificam negrito para muitos desses elementos de texto. No entanto, a maioria dos artigos são traduzidos e o estilo de código diz ao tradutor para deixar essa parte do texto sem tradução.

O estilo de código pode ser embutido (cercado por ') ou blocos de código cercados (cercado por ''') que abrangem várias linhas. Coloque fragmentos de código e caminhos maiores em blocos de código vedados.

* Em comandos de linha de comando, use barras em caminhos de arquivo se eles forem suportados em todas as plataformas. Use barras invertidas para ilustrar comandos executados no Windows, quando apenas barras invertidas são suportadas. Por exemplo, as barras para frente funcionam na CLI do .NET em todas as plataformas, portanto, você usaria dotnet build foldername/filename.csproj em vez de dotnet build foldername\filename.csproj.

Exemplos que utilizam estilos inline

• Faça isto: por predefinição, o Entity Framework interpreta uma propriedade com o nome Id ou ClassnameID como a chave primária.
• Não faça isto: por predefinição, o Entity Framework interpreta uma propriedade com o nome Id ou ClassnameID como a chave primária.
• Faça isto: o pacote Microsoft.EntityFrameworkCore fornece suporte de runtime para EF Core.
• Não faça isto: o pacote Microsoft.EntityFrameworkCore fornece suporte de runtime para EF Core.

Exemplos de blocos de código vedados

• Faça isto: não são enviados comandos para a base de dados cujas instruções alteram apenas um método IQueryable, tal como o seguinte código:

      ```csharp
      var students = context.Students.Where(s => s.LastName == "Davolio")
      ```
  

• Não é isso: nenhum comando é enviado para o banco de dados por instruções que apenas alteram um IQueryable, como var students = context. Students.Where(s => s.LastName == "Davolio").

• Faça isto: por exemplo, para executar o script Get-ServiceLog.ps1 no diretório C:\Scripts, escreva:

      ```powershell
      C:\Scripts\Get-ServiceLog.ps1
      ```
  

• Não faça isto: por exemplo, para executar o script Get-ServiceLog.ps1 no diretório C:\Scripts, escreva: "C:\Scripts\Get-ServiceLog.ps1".

• Todos os blocos de código vedados têm de ter uma etiqueta de linguagem aprovada. Para obter uma lista de etiquetas de linguagem de suporte, veja How to include code in docs (Como incluir código no Docs).

Marcadores de Posição

No texto do parágrafo ou nas etapas processuais, use itálico para texto de espaço reservado que os usuários substituirão por suas próprias informações.

• Isto: Introduza a palavra-passe

• Não é isso: digite "senha"

• Isto: Digite -ppalavra-passe

• Não é este: Digite -p senha

Se desejar que o usuário substitua parte de uma cadeia de caracteres de entrada por seus próprios valores, use texto de espaço reservado marcado por colchetes angulares (menor e < maior que > caracteres).

Opção 1: Use o estilo de código para cercar a palavra do espaço reservado ou a frase abrangente. Por exemplo, você pode usar backticks únicos ' para formatação de código embutido para uma única frase, ou ticks triplos ''' para formatação cercada por código.

`az group delete -n <ResourceGroupName>`

Renderizado como:

az group delete -n <ResourceGroupName>

ou

Opção 2: Use um caractere \ de barra invertida para escapar dos caracteres de colchete angular em Markdown, como \< e \>. Embora apenas a primeira fuga no colchete \< angular esquerdo seja necessária, escapar do colchete \> de fechamento também funciona para consistência. O HTML renderizado não mostra o caractere de escape para o leitor:

az group delete -n \<ResourceGroupName\>

Renderizado como:

az group eliminar -n <ResourceGroupName>

Informe o leitor sobre o espaço reservado: No texto que precede os exemplos de espaço reservado, explique ao leitor que o texto entre parênteses deve ser removido e substituído por valores reais. Recomendamos o uso de itálico para entrada do usuário. Você pode formatar itálico dentro do código embutido entre colchetes angulares:

No exemplo a seguir, substitua o texto <ResourceGroupName> do espaço reservado pelo seu próprio nome de grupo de recursos.

Desencorajamos o uso de chaves { } como espaços reservados sintáticos. Os leitores podem confundir os espaços reservados para chaves com a mesma notação usada em:

• Texto substituível
• Formatar cadeias de caracteres
• Interpolação de cadeias
• Modelos de texto
• Construções de programação semelhantes

Invólucro e espaçamento: Você pode separar nomes de espaço reservado com hífenes ("caso de kebab") ou com sublinhados, ou pode fazê-lo usando maiúsculas e minúsculas Pascal. O caso do Kebab pode gerar erros de sintaxe e os sublinhados podem entrar em conflito com o sublinhado. O uso de todas as letras maiúsculas pode entrar em conflito com constantes nomeadas em muitos idiomas, embora também possa chamar a atenção para o nome do espaço reservado.

<Resource-Group-Name> ou <ResourceGroupName>

Rubricas

Não aplique um estilo embutido como itálico, negrito ou estilo de código embutido aos títulos.

Porquê? Os cabeçalhos têm seus próprios estilos, e misturar outros estilos cria inconsistências.

• Isto: Importar o pacote Microsoft.NET.Sdk.Functions

• Não é isso: Importe o pacote Microsoft.NET.Sdk.Functions

Texto da ligação

Não aplique estilo em linha como itálico ou negrito ao texto do link.

Porquê? As pessoas recorrem a texto de hiperligação padrão para identificar elementos de texto como ligações clicáveis. Estilizar um link como itálico, por exemplo, pode obscurecer o fato de que o texto é um link.

• Isto: O pacote NuGet Microsoft.NET.Sdk.Functions gera o arquivo function.json.

Não é isso: o pacote NuGet Microsoft.NET.Sdk.Functions gera o arquivo function.json.

Teclas e atalhos de teclado

Ao referir-se a teclas ou combinações de teclas, siga estas convenções:

• Coloque a primeira letra dos nomes das teclas em letra maiúscula.
• Envolva os nomes das chaves com <kbd> tags HTML e </kbd> .
• Use "+" para unir teclas que o usuário seleciona ao mesmo tempo.

Exemplos de teclas e atalhos de teclado

• Isto: Selecione Alt++
• Não é isso: pressione ALT+CTRL+S.
• Não é isso: Hit ALT+CTRL+S.

Exceções

Diretrizes de estilo consistentes criam uma experiência confiável para o cliente e simplificam o processo de criação. As exceções a estas orientações devem ser cuidadosamente consideradas.

Se a exceção envolver o uso de um estilo de texto alternativo que normalmente pede código, certifique-se de que não há problema em traduzir o texto em versões localizadas do artigo. Para cenários em que pretende evitar a localização sem utilizar o estilo de código, veja Cadeias de carateres não traduzidas.