Compartir a través de

Instrucciones para la aplicación de formato al texto

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. Si un elemento de formato de texto no está cubierto por esta guía, consulte la Guía de estilo de escritura de Microsoft. En los artículos siguientes se proporcionan instrucciones detalladas sobre el formato de texto:

Elementos de la UI

Los elementos de la interfaz de usuario, como elementos de menú, nombres de diálogo y nombres de cuadros de texto, deben estar en negrita.

  • Esto: En el Explorador de soluciones, haga clic con el botón derecho en el nodo del 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.

Nombres de repositorio y rama de Git

Usa texto en negrita para los nombres de repositorio o rama de Git cuando se seleccionen o introduzcan en las instrucciones.

  • Esto: En el menú de la rama, seleccione main.

  • No es así: en el menú de rama, seleccione "main".

Nuevas introducciones de términos

Use texto cursiva para introducir un nuevo término junto con una definición o explicación. Italice el nuevo término la primera vez que lo use y, a continuación, use texto normal para la definición o explicación.

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

Estilo del 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é? Algunas guías de estilo especifican 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

En el texto de párrafos o pasos de procedimientos, use cursiva para el texto de marcador de posición que los usuarios sustituirán por su propia información.

  • Esto: Escriba la contraseña

  • No es así: escriba "contraseña"

  • Esto: Escriba -ppassword

  • No es así: escriba -p password

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

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>

Informe al lector sobre el marcador de posición: en el texto que precede a los 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 de <marcador de posición> que usa corchetes angulares en los casos en los que los corchetes no se escapen correctamente o el texto no tenga 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 disallowed-html-tag. 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 sucede.

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. El uso de todas las mayúsculas puede entrar en conflicto con las constantes nombradas en muchos idiomas, aunque también puede llamar la atención sobre el nombre de marcador de posición.

<Resource-Group-Name> o <ResourceGroupName>

Encabezados

No aplique un estilo en línea como cursiva, negrita o estilo de código en línea a los encabezados.

¿Por qué? Los encabezados tienen sus propios estilos y la combinación de otros estilos crea incoherencias.

  • Esto: Importar el paquete Microsoft.NET.Sdk.Functions

  • No es así: Importación del paquete Microsoft.NET.Sdk.Functions

Texto del vínculo

No aplique estilo en línea como cursiva o negrita al texto de enlace.

¿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. Aplicar estilo a un vínculo como cursiva, por ejemplo, puede ocultar el hecho de que el texto es un vínculo.

No es así: El paquete NuGet Microsoft.NET.Sdk.Functions genera el archivo function.json.

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: pulse ALT+CTRL+S.
  • No adecuado: dale a ALT+CTRL+S.

Excepciones

Las directrices de estilo coherentes crean una experiencia de cliente confiable y simplifican el proceso de creación. Las excepciones a estas directrices deben tenerse en cuenta detenidamente.

Si la excepción implica usar un estilo de texto alternativo que normalmente requiere código, asegúrese de que está bien traducir el texto en las versiones localizadas del artículo. Para ver los escenarios en los que quiere evitar la localización sin usar el estilo de código, vea Cadenas no localizadas.