Diretrizes de formatação de texto

O uso adequado e consistente de negrito, itálico e estilo de código em elementos de texto melhora a legibilidade e ajuda a evitar confusão. Se um elemento de formatação de texto não for coberto por essa orientação, consulte o Guia de Estilo de Escrita da Microsoft. Os artigos a seguir fornecem diretrizes detalhadas sobre formatação de texto:

• Formatação de elementos de texto comuns

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

• Formatação de elementos comuns do desenvolvedor

Elementos da interface do usuário

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

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

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

Nomes de repositórios e branches do Git

Use texto em negrito para os nomes de repositório Git ou branch quando selecionados ou inseridos nas instruções.

• Isso: no menu de ramificação, selecione principal.

• Não é isso: no menu do branch, selecione "principal".

Introduções de novo termo

Use o texto itálico para introduzir um novo termo junto com uma definição ou explicação. Coloque o novo termo em itálico na primeira vez que você o usar e então utilize formatação regular para a definição ou explicação.

• Assim: 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 um aplicativo Web ser executado.

• Não assim: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 no qual um aplicativo Web deve ser executado.

Estilo de código

Use o estilo de código para:

• Elementos de código, tais como nomes de métodos, nomes de propriedade e palavras-chave de linguagem.
• Comandos SQL
• Nomes de pacote NuGet
• Comandos de linha de comando*
• Nomes de coluna e tabela de banco de dados
• Nomes de recursos que não devem ser localizados (por exemplo, nomes de máquina virtual)
• URLs que você deseja que não sejam clicáveis

Por quê? Alguns guias de estilo especificam negrito para muitos desses elementos de texto. No entanto, a maioria dos artigos é localizada e o estilo de código informa o tradutor para deixar essa parte do texto não traduzida.

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

* Em comandos de linha de comando, use barras duplas em caminhos de arquivo se eles tiverem suporte em todas as plataformas. Use barras invertidas para ilustrar os comandos que são executados no Windows, quando só houver suporte para barras invertidas. Por exemplo, barras duplas 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 usando estilos embutidos

• Assim: Por padrão, o Entity Framework interpreta uma propriedade chamada Id ou ClassnameID como a chave primária.
• Não assim: Por padrão, o Entity Framework interpreta uma propriedade chamada Id ou ClassnameID como a chave primária.
• Assim: O pacote Microsoft.EntityFrameworkCore é compatível com o runtime do EF Core.
• Não assim: O pacote Microsoft.EntityFrameworkCore é compatível com o runtime do EF Core.

Exemplos de blocos de código isolados

• Assim: Nenhum comando é enviado ao banco de dados por instruções que apenas alteram uma IQueryable, como no código a seguir:

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

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

• Assim: Por exemplo, para executar o script Get-ServiceLog.ps1 no diretório C:\Scripts, digite:

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

• Não assim: Por exemplo, para executar o script Get-ServiceLog.ps1 no diretório C:\Scripts, digite: "C:\Scripts\Get-ServiceLog.ps1."

• Todos os blocos de código isolados devem ter uma marca de linguagem de programação aprovada. Para obter uma lista de marcas de linguagem de programação compatíveis, confira Como incluir código em documentos.

Espaços reservados

Em texto de parágrafo ou etapas processuais, use itálico para texto substituível que os usuários substituirão por suas informações próprias.

• Isso: Digite a senha

• Não é isso: insira "senha"

• Isso: insira -psenha

• Não é isso: insira -p senha

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

Opção 1: Use o estilo de código para cercar a palavra de espaço reservado ou a frase abrangente. Por exemplo, você pode usar os acentos graves simples ` para formatação de código em linha para uma única frase ou tiques triplos ``` para formatação com proteção de 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 obter um escape dos caracteres de colchete angular em Markdown, como \< e \> . Embora apenas o primeiro escape no colchete \< angular esquerdo seja necessário, o escape 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 delete -n <ResourceGroupName>

Informe o leitor sobre o espaço reservado: no texto que precede exemplos de espaço reservado, explique ao leitor que o texto entre colchetes 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 em linha entre colchetes angulares:

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

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

• Texto substituível
• Cadeias de caracteres de formato
• Interpolação de cadeia de caracteres
• Modelos de texto
• Constructos de programação semelhantes

Uso de letras e espaçamento: você pode separar nomes de espaço reservado com hifens ("kebab case") ou com sublinhados ou pode fazer isso usando pascal case. O caso Kebab pode gerar erros de sintaxe e sublinhados podem estar em conflito com outros sublinhados. O uso de todas as maiúsculas pode conflitar com constantes nomeadas em muitos idiomas, embora também possa chamar a atenção para o nome de marcador.

<Resource-Group-Name> ou <ResourceGroupName>

Títulos

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

Por quê? Os títulos têm seus próprios estilos e misturar outros estilos cria inconsistências.

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

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

Texto do link

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

Por quê? As pessoas contam com texto de hiperlink padrão para identificar elementos de texto como links clicáveis. Estilizar um link como itálico, por exemplo, pode obscurecer o fato de que o texto é um link.

• Isso: 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 fazer referência a teclas ou combinações de teclas, siga estas convenções:

• Colocar a primeira letra dos nomes de tecla em maiúsculas.
• Cercar os nomes de teclas com <kbd> e </kbd> marcas HTML.
• Use "+" para unir as teclas que o usuário seleciona ao mesmo tempo.

Exemplos de teclas e atalhos de teclado

• Assim: Selecione Alt+Ctrl+S.
• Não assim: pressione ALT+CTRL+S.
• Não assim: Ocorrência ALT+CTRL+S.

Exceções

Diretrizes de estilo consistentes criam uma experiência confiável do cliente e simplificam o processo de criação. As exceções a essas diretrizes devem ser consideradas com cuidado.

Se a exceção envolver o uso de um estilo de texto alternativo que normalmente exige código, verifique se está tudo bem traduzir o texto em versões localizadas do artigo. Para cenários em que você quer impedir a localização sem usar o estilo de código, confira Cadeias de caracteres não localizadas.