Instrucciones para la aplicación de formato al texto

  • Artículo

El hecho de usar de forma coherente y adecuada los estilos de negrita, cursiva o código en elementos de texto facilita su lectura y comprensión.

Negrita

Use la negrita para elementos de IU, como las opciones de los menús y los nombres de los cuadros de diálogo o los campos de entrada.

Ejemplos

  • Adecuado: en el Explorador de soluciones, haga clic con el botón derecho en el nodo de proyecto y seleccione Agregar > Nuevo elemento.
  • No adecuado: en el Explorador de soluciones, haga clic con el botón derecho en el nodo de proyecto y seleccione Agregar > Nuevo elemento.
  • No adecuado: en el Explorador de soluciones, haga clic con el botón derecho en el nodo de proyecto y seleccione Agregar > Nuevo elemento.

Cursiva

Use la cursiva para:

  • Presentar términos nuevos junto con una definición o explicación.
  • Nombres de archivos o carpetas y rutas de acceso
  • Datos proporcionados por el usuario.

Ejemplos

  • Adecuado: En App Service, una aplicación se ejecuta en un plan de App Service. Un plan de App Service define un conjunto de recursos de proceso para la ejecución de una aplicación web.
  • No adecuado: en App Service, una aplicación se ejecuta en un "plan de App Service". Un plan de App Service define un conjunto de recursos informáticos para ejecutar una aplicación web.
  • Adecuado: Reemplace el código de HttpTriggerCSharp.cs por el código siguiente:
  • No adecuado: Reemplace el código de HttpTriggerCSharp.cs por el siguiente código.
  • Adecuado: Escriba ContosoUniversity para el nombre y, después, seleccione Agregar.
  • No adecuado: Escriba "ContosoUniversity" para el nombre y, después, seleccione Agregar.

Estilo de código

Use el estilo de código para:

  • Elementos de código, como nombres de métodos y de propiedades o palabras clave de un lenguaje
  • Comandos SQL
  • Nombres de paquetes NuGet
  • Comandos de la línea de comandos*
  • Nombres de tablas y columnas de bases de datos
  • Nombres de recursos que no deben traducirse (por ejemplo, nombres de máquinas virtuales)
  • Direcciones URL en las que no quiera que se pueda hacer clic

¿Por qué? En las guías de estilo anteriores se especifica la negrita para muchos de estos elementos de texto, pero la mayoría de los artículos están traducidos y el estilo de código indica al traductor que deje esa parte del texto sin traducir.

El estilo de código puede estar insertado (rodeado por `) o con bloques de código delimitados (rodeados por ```) que abarcan varias líneas. En el caso de los fragmentos de código y las rutas de acceso de mayor longitud, use bloques de código delimitados.

* En los comandos de la línea de comandos, use barras diagonales en rutas de acceso de archivos si se admiten en todas las plataformas. Use barras diagonales inversas para mostrar los comandos que se ejecutan en Windows, cuando solo se admitan barras diagonales inversas. Por ejemplo, las barras diagonales funcionan en la CLI de .NET en todas las plataformas, por lo que usaría dotnet build foldername/filename.csproj en lugar de dotnet build foldername\filename.csproj.

Ejemplos de uso de estilos insertados

  • Adecuado: De forma predeterminada, Entity Framework interpreta una propiedad con el nombre Id o ClassnameID como clave principal.
  • No adecuado: De forma predeterminada, Entity Framework interpreta una propiedad con el nombre Id o ClassnameID como clave principal.
  • Adecuado: El paquete Microsoft.EntityFrameworkCore proporciona compatibilidad en tiempo de ejecución con EF Core.
  • No adecuado: El paquete Microsoft.EntityFrameworkCore proporciona compatibilidad en tiempo de ejecución con EF Core.

Ejemplos de bloques de código delimitados

  • Adecuado: Las instrucciones que solo cambien un valor IQueryable, como en el código siguiente, no enviarán ningún comando a la base de datos:

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

  • No adecuado: Las instrucciones que solo cambien un valor IQueryable, como var students = context.Students.Where(s => s.LastName == "Davolio"), no enviarán ningún comando a la base de datos.

  • Adecuado: Por ejemplo, para ejecutar el script Get-ServiceLog.ps1 en el directorio C:\Scripts, escriba esto:

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

  • No adecuado: Por ejemplo, para ejecutar el script Get-ServiceLog.ps1 en el directorio C:\Scripts, escriba esto: "C:\Scripts\Get-ServiceLog.ps1."

  • Todos los bloques de código delimitados deben tener una etiqueta de idioma aprobada. Para obtener una lista de etiquetas de idioma compatibles, vea Inclusión de código en documentos.

Marcadores de posición

Si quiere que el usuario reemplace parte de una cadena de entrada con sus propios valores, use texto de marcador de posición delimitado por corchetes angulares (los caracteres de menor que < y mayor que >).

Opción 1: use el estilo de código para delimitar la palabra de marcador de posición o la frase correspondiente. Por ejemplo, puede usar signos de acento grave únicos ` para el formato de código insertado para una sola frase, o triples ``` para el formato con de delimitación de código.

`az group delete -n <ResourceGroupName>`

Se representa como:

az group delete -n <ResourceGroupName>

o bien

Opción 2: use un carácter de barra \ para escapar los caracteres de corchete angular en Markdown, como \< y \>. Aunque solo se requiere el primer escape en el corchete angular izquierdo \<, el escape del corchete de cierre \> también se puede usar para mantener la coherencia. El código HTML representado no muestra el carácter de escape al lector:

az group delete -n \<ResourceGroupName\>

Se representa como:

az group delete -n <ResourceGroupName>

Informar al lector sobre el marcador de posición: en el texto anterior a estos ejemplos de marcador de posición, explique al lector que el texto entre corchetes debe quitarse y sustituirse por valores reales. Se recomienda el uso de cursiva para la entrada del usuario. Puede dar formato a cursiva dentro del código insertado entre corchetes angulares:

En el ejemplo siguiente, reemplace el texto del marcador de posición <ResourceGroupName> por su propio nombre de grupo de recursos.

Precaución

El sitio de Microsoft Learn no representa <el texto del marcador> de posición que usa corchetes angulares en los casos en los que los corchetes no se escapan correctamente o el texto no tiene formato de código. El proceso de compilación de Microsoft Learn interpreta la frase de <marcador> de posición como una etiqueta HTML que podría ser peligrosa para el explorador del lector y la marca como una etiqueta html-no permitida. Verá una sugerencia en el informe de compilación y la palabra de marcador de posición no se representa en la salida de la página de Microsoft Learn cuando esto suceda.

Para evitar la pérdida de contenido en los marcadores de posición, use caracteres de formato code o de escape (\<\>) como se ha descrito anteriormente.

No se recomienda usar llaves { } como marcadores de posición sintácticos. Los lectores pueden confundir los marcadores de posición de llaves con la misma notación usada en:

  • Texto reemplazable
  • Cadenas de formato
  • Interpolación de cadenas
  • Plantillas de texto
  • Construcciones de programación similares

Espacios, mayúsculas y minúsculas: puede separar los nombres de marcador de posición con guiones ("kebab case") o con guiones bajos, o puede hacerlo mediante el uso de "Pascal case". El uso de kebab case puede generar errores de sintaxis y los guiones bajos pueden entrar en conflicto con el subrayado. Usar todo en mayúsculas puede entrar en conflicto con las constantes con nombre en muchos idiomas, aunque también puede llamar la atención sobre el nombre del marcador de posición.

<Resource-Group-Name> o <ResourceGroupName>

Texto de encabezados y vínculos

No aplique ningún estilo de línea, como la cursiva o la negrita, en encabezados o textos de hipervínculos.

¿Por qué?

Los usuarios identifican los elementos de texto como vínculos en los que se puede hacer clic mediante el texto de hipervínculo estándar. Si, por ejemplo, aplica la cursiva en un vínculo, puede que sea difícil identificarlo como tal. Los encabezados cuentan con sus propios estilos, por lo que agregar otros estilos no dará un buen resultado.

Ejemplos de encabezados y texto de vínculos

  • Adecuado: la generación del archivo function.json se realiza mediante el paquete NuGet Microsoft.NET.Sdk.Functions.

  • No adecuado: la generación del archivo function.json se realiza mediante el paquete NuGet Microsoft.NET.Sdk.Functions.

  • Adecuado:

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

  • No adecuado:

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

Teclas y métodos abreviados de teclado

Al hacer referencia a las teclas o las combinaciones de teclas, siga estas convenciones:

  • Ponga en mayúscula la primera letra de los nombres de teclas.
  • Rodee los nombres de teclas con las etiquetas HTML <kbd> y </kbd>.
  • Use "+" para combinar las teclas que el usuario presiona al mismo tiempo.

Ejemplos de teclas y métodos abreviados de teclado

  • Adecuado: presione Alt+Ctrl+S.
  • No adecuado: Presione ALT+CTRL+S.
  • No adecuado: Pulse ALT+CTRL+S.

Excepciones

Las instrucciones de estilo no son reglas estrictas. En contextos en los que perjudiquen la legibilidad, hágalo de otra forma. Por ejemplo, una tabla HTML que contenga principalmente elementos de código podría tener un aspecto demasiado denso al usar únicamente estilo de código. Puede elegir el estilo de negrita en ese contexto.

Si elige un estilo de texto alternativo en el que normalmente se llama al código, asegúrese de que es correcto que el texto se traduzca en las versiones localizadas del artículo. El código es el único estilo que impide la traducción de forma automática. Para ver los escenarios en los que quiere evitar la localización sin usar el estilo de código, vea Cadenas no localizadas.