Compartilhar via

Diretrizes de formatação de texto

  • Artigo

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.

Negrito

Use negrito para elementos de interface do usuário, tais como seleções de menu, nomes de caixas de diálogo e nomes de campos de entrada.

Exemplos

  • 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.
  • 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.
  • 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.

Itálico

Use itálico para:

  • Apresentar novos termos, junto com uma definição ou explicação.
  • Nomes de arquivos, nomes de pastas, caminhos.
  • Entrada do usuário.

Exemplos

  • 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.
  • Assim: substitui o código em HttpTriggerCSharp.cs pelo código a seguir.
  • Não assim: Substitua o código em HttpTriggerCSharp.cs pelo código a seguir.
  • Assim: insira ContosoUniversity para o Nome e, em seguida, selecione Adicionar.
  • Não assim: insira "ContosoUniversity" para o Nome e, em seguida, selecione Adicionar.

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ê? Guias de estilo mais antigos 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

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 anterior a esses 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.

Cuidado

O site do Microsoft Learn não renderiza o texto de <espaço reservado> que usa colchetes angulares em casos em que os colchetes não são escapados corretamente ou o texto não está formatado em código. O processo de build do Microsoft Learn interpreta a frase de <espaço reservado> como uma marca HTML que pode ser perigosa para o navegador do leitor e a sinaliza como uma marca disallowed-html-tag. Você verá uma sugestão no relatório de build, e a palavra de espaço reservado não será renderizada na saída da página Microsoft Learn quando isso acontecer.

Para evitar a perda de conteúdo em espaços reservados, use a formatação code ou os caracteres de escape (\< \>) conforme descrito anteriormente.

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. Letras todas maiúsculas podem entrar em conflito com constantes nomeadas em muitos idiomas, embora também possam chamar a atenção para o nome do espaço reservado.

<Resource-Group-Name> ou <ResourceGroupName>

Títulos e texto de link

Não aplique um estilo embutido como negrito ou itálico para títulos ou texto de hiperlink.

Por quê?

As pessoas contam com texto de hiperlink padrão para identificar elementos de texto como links clicáveis. Aplicar o estilo itálico a um link poderá, por exemplo, obscurecer o fato de que o texto é um link. Os títulos têm seus próprios estilos e misturar outros estilos neles terá aparência ruim.

Exemplos de cabeçalhos e texto de link

  • Isto: o arquivo function.json é gerado pelo pacote NuGet Microsoft.NET.Sdk.Functions.

  • Não isto: o arquivo function.json é gerado pelo pacote NuGet Microsoft.NET.Sdk.Functions.

  • Assim:

    ### The Microsoft.NET.Sdk.Functions package

  • Não assim:

    ### The *Microsoft.NET.Sdk.Functions* package

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

As diretrizes de estilo não são regras rígidas. Em contextos nos quais elas podem prejudicar a legibilidade, faça algo diferente. Por exemplo, uma tabela HTML cheia de elementos de código poderá parecer muito confusa com estilo de código em todo lugar. Você pode escolher usar estilo negrito nesse contexto.

Se você escolher um estilo de texto alternativo, no qual o código normalmente é necessário, verifique se não há nenhum problema em traduzir o texto em versões localizadas do artigo. O código é o único estilo que impede automaticamente a tradução. 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.