Guía de estilo

El enfoque de GitHub Docs sobre el estilo

• Nuestra guía de estilo busca la simplicidad. Las directrices deben ser fáciles de aplicar a una variedad de escenarios.
• No se trata de decidir sobre lo que es correcto o incorrecto de acuerdo con las reglas de gramática o la guía de estilo, sino sobre lo que es mejor para nuestros usuarios. Somos flexibles y estamos abiertos a los cambios siempre y cuando se mantenga la coherencia.
• Para ampliar la guía de estilo a medida que crecen nuestro equipo y nuestros conjuntos de documentación, y para crear contenidos de alta calidad y significativos que sirvan a los usuarios, centramos nuestra atención en escenarios de gran impacto y valor en lugar de intentar cubrir exhaustivamente todas las cuestiones de estilo.
• La coherencia y la corrección gramatical son importantes, pero no tanto como la claridad y el significado.
• Al tomar una decisión de estilo o estructura, consideramos el flujo de información dentro de la unidad de contenido y el contexto de la información.
• Cuando una cuestión específica de la documentación de ayuda no está contemplada en la guía de estilo, nos basamos en estos principios para tomar una decisión. Si un revisor pregunta al respecto, estamos dispuestos a discutir la decisión.

Eventos del registro de auditoría

Documentamos cada uno de los eventos que pueden aparecer en los registros de auditoría para cada tipo de cuenta: de usuario, de organización y de empresa.

•         [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/security-log-events)
  

•         [AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/audit-log-events-for-your-organization)
  

•         [AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/reviewing-audit-logs-for-your-enterprise/audit-log-events-for-your-enterprise) 
  

Al escribir la descripción de un evento del registro de auditoría, describe el evento que tuvo lugar de forma que se aplique a todas las versiones, mediante voz pasiva y tiempo pasado. No comiences la frase con expresiones que ya están implícitas en el contexto del artículo, como "Desencadenado por".

•         **Uso**: se ha cambiado la visibilidad de un repositorio.
  

•         **Use:** el examen de secretos se ha habilitado para todos los repositorios nuevos.
  

•         **Evita**: un propietario de la organización ha deshabilitado un requisito de autenticación en dos fases para la organización.
  

•         **Evite:** se desencadena cuando un usuario actualiza los repositorios a los que puede acceder un codespace.
  

Alertas

Las alertas enfatizan la información dentro de un artículo de especial importancia y que justifica la interrupción del flujo de información.

Use las alertas con moderación. No use alertas consecutivas ni más de una por sección.

Las alertas deben ser concisas. Si la información consiste en más de un par de oraciones o requiere una lista ordenada o desordenada, considere la posibilidad de colocar la información bajo un encabezado de sección.

Tipos de alerta

Usamos cinco tipos de alertas: Nota, Consejo, Importante, Advertencia y Precaución.

Nota:

Proporciona contexto adicional que los usuarios pueden necesitar tener en cuenta. Las tareas se pueden realizar sin la información de las alertas de nota, pero algunos usuarios, en algunos contextos, pueden sacar provecho de la nota.

Las notas son especialmente útiles para comunicar información explicativa que no es fundamental para el proceso que se describe:

• Advertencias que podrían afectar al resultado de un proceso, como la configuración de usuario específica.
• Productos y características que están sujetos a cambios en la disponibilidad, como los de versión preliminar pública o cerrar.

Por ejemplo, Evaluación de alertas del análisis de secretos usa una nota para informar a los usuarios de que los metadatos de los tokens de GitHub están actualmente en versión preliminar pública.

Sugerencia

Recomendaciones, procedimientos recomendados o sugerencias de productos. Los consejos contienen información no esencial que los usuarios pueden seguir a su discreción. Especialmente útil en artículos dirigidos a nuevos usuarios.

Por ejemplo, Personaliza tu perfil usa una alerta de sugerencia para ayudar a los usuarios a comprender qué esperar cuando hacen @mention a una organización.

Importante

Resalta la información clave que los usuarios necesitan saber para lograr su objetivo.

Advertencia

Resalta los posibles riesgos que un usuario debe tener en cuenta antes de iniciar o continuar con una tarea.

Las alertas de advertencia son especialmente pertinentes para los procesos que se producen fuera de la interfaz de usuario de GitHub, como en la línea de comandos o a través de una API.

Por ejemplo, Acerca de las autoridades de certificación de SSH incluye instrucciones para la línea de comandos y usa una alerta de advertencia para informar a los usuarios de que, una vez emitidos, los certificados no se pueden revocar:

Precaución

Alerta a los usuarios de acciones peligrosas o destructivas que requieren extrema precaución antes de realizarlas, especialmente cuando hay un riesgo de seguridad o podría producirse una pérdida de datos.

Por lo general, las alertas de precaución solo serán necesarias al describir los procesos que se producen fuera de la interfaz de usuario de GitHub, como en la línea de comandos o a través de una API.

Alertas de formato

Usamos formato y colores estándar para diferentes tipos de alertas en conjuntos de documentos.

Las alertas se representan mediante Markdown.

Nota:

> [!NOTE]
> Keep this in mind.

Sugerencia:

> [!TIP]
> Here's a suggestion.

Advertencia:

> [!WARNING]
> Be careful.

Precaución:

> [!CAUTION]
> Be extremely careful.

La sintaxis líquida para las alertas sigue siendo compatible y puede seguir apareciendo en artículos anteriores, pero no debe usarse para nuevas alertas.

Para obtener más información sobre el formato de las alertas, consulta "Alertas" en Uso de Markdown y Liquid en la documentación de GitHub.

Llamada a la acción (CTA)

Una llamada a la acción es un vínculo o un botón que pide a los usuarios que realicen el siguiente paso en su recorrido. Enviará a un usuario a otra ubicación.

El componente clave de una llamada a la acción es que ayuda al usuario a hacer lo que estaba intentando hacer, ya sea guiándolos al paso siguiente o llevándoles a un producto o característica que necesitan.

Al considerar cuándo usar un CTA, plantéate las siguientes preguntas:

• ¿Hay un paso siguiente lógico o necesario para el usuario? Esta puede ser la siguiente información que necesitan o una característica que les ayude a realizar su tarea.
• ¿Hay alguna necesidad empresarial de enviar el usuario a ese lugar?

Solo debemos usar una llamada a la acción cuando la respuesta a ambas preguntas sea sí.

¿En qué se diferencia una llamada a la acción de un vínculo?

Una llamada a la acción es una dirección explícita para que el usuario realice una acción inmediata, como "Prueba Copilot de forma gratuita" o "Crea tu propio repositorio". Un CTA en nuestra documentación solo debe dirigir a los usuarios a un dominio propiedad de GitHub.

Por ejemplo, la CTA de Configuración de una versión de prueba de GitHub Enterprise Cloud vincula a una página de ventas de empresa en GitHub.com.

Creación de CTA

Para crear una dirección URL de CTA válida con los parámetros correctos, use el script del generador de CTA al extraer el repositorio de documentos:

npm run cta-builder

El script le guiará a través de un proceso interactivo para:

• Seleccione el producto GitHub adecuado (ref_product)
  • Use github como valor predeterminado cuando el vínculo no sea específico de una característica o producto determinado.
• Elija el tipo de acción (ref_type)
• Especificar el estilo de formato (ref_style)
• Opcionalmente, seleccione un plan específico (ref_plan)

El script proporciona todas las opciones disponibles para cada parámetro y genera una dirección URL de llamada a la acción completa y válida al final. Use esta herramienta para asegurarse de que está utilizando los valores aprobados y actuales para los parámetros de CTA.

Por ejemplo, el script podría generar una dirección URL como:

https://github.com/account/enterprises/new?ref_product=ghec&ref_type=trial&ref_style=button&ref_plan=enterprise

Código

Bloques de código

Mantén las líneas de los ejemplos de código en unos 60 caracteres para evitar que los lectores se tengan que desplazar horizontalmente en el bloque de código. Localiza el texto explicativo antes del bloque de código, en lugar de usar comentarios dentro del bloque de código. Para más información sobre la sintaxis y el formato de los bloques de código, consulta Uso de Markdown y Liquid en la documentación de GitHub.

Dentro de los bloques de código:

• Especifica el idioma del ejemplo después del primer delimitador de código. Para obtener una lista de todos los idiomas admitidos, consulta Lenguajes de código en el repositorio github/docs.

• No uses HTML para aplicar un estilo a un bloque de código o marcarlo.

• Estiliza los marcadores de posición que los usuarios necesiten reemplazar con sus propios valores en mayúsculas.

  •           **Use:**`git checkout -b BRANCH-NAME`
    

  •       **Evitar:**`git checkout -b <branch-name>`
    

• No utilices indicadores de comando como $ antes del comando. Estos mensajes hacen que sea difícil que los lectores copien y peguen el comando.

  • Si muestras un comando y la salida del comando, comenta la salida en el ejemplo.

  •       **Use:**
    

    command
    # output
    

  •       **Evitar:**
    

    $ command
    output
    

• Si el ejemplo de código incluye { o } que debe representarse, encapsula esa sección en {% raw %}{% endraw %} para deshabilitar el procesamiento de Liquid para ella. * Use:

    GITHUB_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}
    

  •       **Evitar:**
    

    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    

• Si el ejemplo de código incluye contenido que se debe analizar, encapsule esa sección en etiquetas <pre>``</pre> para analizarlo en lugar de escapar el contenido de la sección.

Comandos

Usa bloques de código en línea para hacer referencia a nombres de comandos cortos. * Usar: Para comprobar el estado de un clúster en ejecución, usa el comando ghe-cluster-status.

Usa bloques de comandos en el caso de comandos más largos o complejos. * Usar: Para habilitar el modo de mantenimiento en función de la ventana de programación, conéctate al shell administrativo de cualquier nodo de clúster y ejecuta:

ghe-cluster-maintenance -s

No incluyas indicaciones del comando como $. Evita vínculos insertados en los nombres de comando.

Salidas

Si muestras la salida de un comando, convierte la salida en comentario en el ejemplo para que la gente pueda copiar y pegar el comando y ejecutarlo sin modificaciones.

•         **Use:**
  

  git lfs install
  # Git LFS initialized.
  

•         **Evitar:**
  

  $ git lfs install
  > Git LFS initialized.
  

Ejemplos

Cuando los ejemplos de código hagan referencia a un archivo más grande, muestra la sección pertinente del archivo para que los usuarios comprendan cómo editar su propio código en contexto. * Use:

on:
  schedule:
    - cron:  "40 19 * * *"

•         **Evitar:**
  

schedule:
  - cron:  "40 19 * * *"

Nombres de archivo y nombres de directorio

Use acentos graves para dar formato a las referencias a nombres de archivo y nombres de directorio en una fuente monoespacial. Si un tipo de archivo generalmente sigue una convención específica sobre el uso de mayúsculas, como el uso de letras mayúsculas para los archivos LÉAME, usa la convención establecida.

•         **Usar:** En tu archivo `README.md`, añade información sobre tu repositorio.
  

•         **Usar:** En el directorio `.github/workflows/`, cree el archivo `example-workflow.yml`.
  

•         **Evita:** En tu directorio _.github/workflows/_, crea el archivo `example-workflow.yml`.
  

•         **Evitar:** Eliminar el archivo **example.js**.
  

Sangría

En los ejemplos de YAML, como acciones y archivos de flujo de trabajo, utiliza dos espacios para indentar las líneas dentro de listas anidadas y secuencias de bloques.

•         **Use:**
  

    steps:
      - uses: actions/checkout@v5
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python }}

Para aplicar sangría a elementos reutilizables, consulte data/reusables/README.md.

Flujos de trabajo programados

Las ejecuciones de flujos de trabajo se retrasan cuando se ejecutan demasiados flujos de trabajo a la vez. Dado que muchos usuarios copian código de GitHub Docs, deberíamos usar ejemplos que alejen a los usuarios de las horas de congestión.

• No uses ejemplos que se ejecuten en la hora, ya que son los tiempos más congestionados.
• No uses ejemplos que se ejecuten con mayor frecuencia de la necesaria. Por ejemplo, en lugar de ejecutarse cada cinco minutos, considera si tiene más sentido que el ejemplo se ejecute cada 30 minutos.
• Usa una hora diferente para cada ejemplo.

Énfasis

Use negrita para resaltar palabras o partes de una oración. Use énfasis con moderación (no más de cinco palabras contiguas) y recuerde que es una ayuda visual para detectar a los usuarios visualmente.

• No ponga en negrita palabras que tengan otro formato aplicado, como todo mayúsculas para el texto de marcador de posición.
• Para la accesibilidad, no use negrita como la única manera de transmitir significado o énfasis.

Por ejemplo:

•         **Uso:** Las cuentas de usuario administradas **no pueden crear contenido público** ni colaborar fuera de su empresa.
  

•         **Evite:** junto a _**Título**_, agregue una etiqueta descriptiva para la clave nueva.
  

Mensajes de error

Cuando se incluya el texto de un mensaje de error de un producto o interfaz de GitHub en un artículo, debe darse formato al texto según la interfaz donde aparece el mensaje.

• Si el mensaje aparece en la interfaz web de GitHub, o en una aplicación cliente gráfica como GitHub Desktop o GitHub Mobile, debe tratarse el mensaje como otro texto en la interfaz de usuario. Para obtener más información, consulta Texto de la interfaz de usuario.

• Si el mensaje aparece en una interfaz de línea de comandos, en la salida de un registro o en una respuesta de una API, debe reproducirse el texto exactamente y usar comillas invertidas para formatear el mensaje usando una fuente monoespaciada.

Expiración del contenido

En general, no documente el contenido que expirará. Cualquier persona que visite GitHub Docs debe estar seguro de que la información es precisa y está actualizada.

Si debe documentar el contenido que sabe expirará, puede usar el linter de contenido para etiquetar y realizar un seguimiento de la fecha de expiración del contenido. Esto marcará el contenido como obsoleto y evitará el seguimiento de las fechas de expiración fuera del propio contenido. Consulta Uso del linter de contenido para obtener información sobre cómo dar formato a las etiquetas de contenido que expiran.

Notas al pie

Evita el uso de notas al pie siempre que sea posible. En su lugar, considere si podría usar una alerta o presentar la información de otra manera. Puedes encontrar algunos ejemplos de alternativas a las notas al pie en NICE.org.uk.

Si tienes que usar notas al pie, usa notas al pie nativas de Markdown ([^1]). Los marcadores de nota al pie estarán hipervinculados a la referencia de la nota al pie, que se mostrará en la parte inferior de la página con un vínculo de retorno al marcador.

Ten en cuenta que, independientemente del identificador que uses (letras, palabras), las notas al pie se representarán como números secuenciales.

          [^1]: Not to be confused with Davy Jones of The Monkees

          [^2]: Also humans

| | Mona | Ursula | Paul | Davy Jones[^1] |
|---|---|---|---|---|
|Favorite pastime| Shipping code | Tricking mermaids[^2] | Predicting sports | Haunting seafarers |
|Uses powers for good| Yes | No | Yes | No |
[^1]: Not to be confused with Davy Jones of The Monkees
[^2]: Also humans

encabezados

Los encabezados deben describir adecuadamente el contenido que hay debajo. Los encabezados pueden seguir las instrucciones para escribir títulos o se pueden escribir como preguntas. Usa solo una mayúscula inicial en las frases de todos los encabezados.

Si un artículo tiene encabezados, estos deben comenzar con un encabezado de nivel H2. Puede usar encabezados de nivel H3 y H4 para organizar aún más el contenido en grupos relacionados, pero no puede omitir los niveles de encabezado. Debe haber contenido entre un encabezado y un subtítulo, como una introducción. * Use:

## HEADER (H2)

TEXT

### SUBHEADER (H3)

TEXT

#### SUBHEADER (H4)

TEXT

•         **Evitar:**
  

  ## HEADER (H2)
  
  #### SUBHEADER (H4)
  

Cada encabezado en el mismo nivel de una página debe ser único.

•         **Use:**
  

  ## Examples  (H2)
  
  TEXT
  
  ### Prompts for writing code (H3)
  
  TEXT
  
  ### Prompts for writing tests (H3)
  
  TEXT
  

•         **Use:**
  

  ## Prompts for writing code (H2)
  
  TEXT
  
  ### Example (H3)
  
  TEXT
  
  ## Prompts for writing tests (H2)
  
  TEXT
  
  ### Example (H3)
  
  TEXT
  

•         **Evitar:**
  

  ## Example prompts (H2)
  
  TEXT
  
  ### Example (H3)
  
  TEXT
  
  ### Example (H3)
  
  TEXT
  

Imágenes

Usamos imágenes estáticas, como capturas de pantalla, diagramas y gráficos en todos los documentos para complementar la información textual.

No uses GIF animados en la documentación.

Texto alternativo

Cada imagen debe incluir texto alternativo que proporcione un equivalente textual de la información visual.

• Expresa la idea principal o el significado de la imagen, en lugar de describirla literalmente.
• Usa entre 40 y 150 caracteres.
• Termina con un signo de puntuación. Por lo general, debe ser un punto a menos que el texto alternativo describa una imagen de texto que termine con otros signos de puntuación, como un signo de interrogación o de exclamación.
• No empieces con "Image..." o "Graphic...". Los lectores de pantalla lo dicen automáticamente.
• Comienza con el tipo de gráfico: "Captura de pantalla de..." o "Diagrama que muestra..."
• Sigue el idioma estándar que se usa para describir los elementos de la interfaz de usuario en el texto del artículo.
• Coloca títulos de varias palabras, como nombres de elementos de menú, entre comillas dobles ("").
• Si un área de la imagen está resaltada visualmente, describe cómo. Así los usuarios de lectores de pantalla podrán comprender y describir a un amigo o compañero vidente lo que se debe buscar desde el punto de vista del lenguaje visual.

Texto alternativo para capturas de pantalla

El texto alternativo proporciona una breve descripción del contenido de una captura de pantalla para beneficio de las personas que no pueden verlo.

• El texto alternativo solo necesita incluir los elementos más relevantes de una imagen, no todos los detalles.
• No está pensado para proporcionar instrucciones sobre el uso de la interfaz de GitHub. Deben incluirse en el texto que acompaña al artículo.

Formato

Captura de pantalla de Product name + UI element que se muestra. El UI element + state of the element/controls y su keyboard shortcut XYZ se resaltan en naranja oscuro.

• Para Product name, usa el nombre de producto o característica de GitHub, como "GitHub Actions" o "GitHub", en lugar de simplemente "GitHub".
• Usa una variable para la palabra GitHub como hacemos en la copia en ejecución: {% data variables.product.prodname_dotcom %}
• Describe los elementos de la interfaz de usuario de forma coherente con la documentación escrita.
• Sé flexible con el orden de las palabras cuando sea necesario para mayor claridad.
  • Por ejemplo, escribe "Captura de pantalla del menú Depurar en Visual Studio Code..." en lugar de "Captura de pantalla del menú Depurar de Visual Studio Code", para evitar varios nombres en una fila.

Ejemplos

Captura de pantalla de los confirmadores de GitHub por tabla del repositorio. El icono de kebab horizontal y el botón "Descargar informe CSV" se resaltan en naranja oscuro.

Captura de pantalla de las opciones de archivo en un repositorio de GitHub. Un botón con una flecha que indica un menú desplegable, con la etiqueta "Código", está resaltado en naranja oscuro.

Texto alternativo para diagramas y gráficos

Explica la información transmitida en el diagrama o el gráfico en el texto de la página.

Usa texto alternativo para expresar la idea principal de la imagen, sin duplicar el texto de la página web.

Ejemplo

Diagrama que muestra un proceso de cinco pasos mediante el cual un ejecutor de GitHub Actions se puede agregar automáticamente a clases nombradas de ejecutores y luego ser solicitado por trabajos específicos.

Por ejemplo, consulte la explicación que acompaña a este diagrama en la documentación de Acciones.

Texto alternativo para imágenes de interfaces de línea de comandos

No uses capturas de pantalla de interfaces de línea de comandos para transmitir comandos y su salida. En su lugar, proporciona directamente los comandos que debe emplear el usuario. Para más información, consulta la sección Comandos de la guía de estilo.

Al usar una captura de pantalla de una interfaz de línea de comandos para mostrar elementos de la interfaz de usuario, sigue las instrucciones de texto alternativo estándar de las capturas de pantalla.

Nombres de archivo para imágenes

Sea descriptivo al asignar nombres a archivos de imagen: incluya el nombre, la acción y el elemento de la interfaz de usuario en el nombre de archivo. Refleje el lenguaje del producto. Use el caso de kebab. No utilice las condiciones de Liquid en los nombres de archivo. Si reemplaza una imagen, usa el nombre de archivo exacto.

•           **Use:**`data-pack-purchase-button.png`
  

•         **Evitar:**`purchase_button.png`
  

•         **Evitar:**`purchase-button-for-admins.png`
  

Capturas de pantalla

Para información sobre cómo crear y controlar las versiones de las imágenes, consulta Creación y actualización de capturas de pantalla.

Diagramas

Para obtener información sobre cómo crear diagramas, consulte Crear diagramas para GitHub Docs.

Lenguaje inclusivo

Como sede de la mayor comunidad de desarrolladores del mundo, GitHub se compromete a promover la diversidad y la inclusión en todos los aspectos de lo que hacemos. Toda nuestra documentación es inclusiva y respetuosa con nuestro público, que está formado por personas de todo el planeta en circunstancias muy diversas. Cuando redactamos nuestra documentación, utilizamos palabras inclusivas, antirracistas y accesibles.

Cada palabra por sí sola puede ser pequeña, pero juntas pueden crear comunidad, pertenencia y equidad. Debes ser empático en todas las elecciones de palabras y estilo. Debes ser preciso al hacer referencia a personas y comunidades.

Recursos sobre el lenguaje inclusivo

La Guía de estilo de Microsoft ofrece recursos sobre comunicación sin prejuicios, términos de accesibilidad y escritura para todas las capacidades: * Comunicación sin prejuicios * Escritura para todas las capacidades * Herramientas de accesibilidad

Más recursos para aprender sobre el lenguaje y el estilo inclusivos y accesibles:

• Guía de estilo de contenido de MailChimp: * Escribir sobre las personas * Escribir para la accesibilidad

•         [Directrices de legibilidad](https://readabilityguidelines.co.uk/)
  

•         [Guía de estilo consciente](https://consciousstyleguide.com/)
  

Métodos abreviados de teclado

Para presentar métodos abreviados de teclado, sigue la Guía de estilo de Microsoft, salvo por las siguientes diferencias:

• Usa la etiqueta HTML <kbd> para cada clave individual.

  •           **Use:**`<kbd>Command</kbd>+<kbd>B</kbd>`
    

  •       **Evitar:**`Command+B`
    

• Usa palabras completas en lugar de símbolos para las teclas modificadoras de Apple.

  •           **Use:**`Command`
    

  •       **Evitar:**`⌘`
    

• Usa símbolos para las teclas de caracteres especiales, no palabras completas.

  •       **Usar:**`.`, `,` y `→`.
    

  •       **Evitar:**`Period`, `Comma` y `Right arrow`.
    

Usos destacados

A continuación se destacan algunos aspectos del uso sobre cómo presentamos los atajos de teclado en nuestra documentación.

• La sintaxis básica es mostrar las claves con + entre combinaciones de teclas, sin espacios.

  •       **Usar:**`<kbd>Command</kbd>+<kbd>B</kbd>`, que se representa como <kbd>Comando</kbd>+<kbd>B</kbd>.
    

  •       **Evitar:**`<kbd>Command</kbd> + <kbd>B</kbd>` o `<kbd>Command + B</kbd>` que se representan como <kbd>Command</kbd> + <kbd>B</kbd> o <kbd>Command + B</kbd>.
    

• Escribe siempre en mayúscula las teclas de letra en referencias generales y métodos abreviados de teclado.

  •       **Usar:**<kbd>Comando</kbd>+<kbd>B</kbd>
    

  •       **Evitar:**<kbd>Comando</kbd>+<kbd>b</kbd>.
    

• Usa las teclas modificadoras correctas para cada sistema operativo.

          **Nota:** En Windows y Linux <kbd>Ctrl</kbd> se escribe de forma abreviada, mientras que en Mac se escribe de forma completa: <kbd>Control</kbd>.
  

  • En Windows y Linux:

    •     **Usar:**<kbd>Ctrl</kbd>, <kbd>Alt</kbd>.
      

    •     **Evitar:**<kbd>Controlar</kbd>
      

  • Para Mac:

    •     **Usar:**<kbd>Comando</kbd>, <kbd>Opción</kbd>, <kbd>Control</kbd>.
      

    •     **Evitar:**<kbd>Cmd</kbd>, <kbd>⌘</kbd>, <kbd>Opt</kbd>, <kbd>⌥</kbd>, <kbd>Ctrl</kbd>, <kbd>⌃</kbd>
      

• No confundas las combinaciones de teclas con las teclas de una secuencia.

  •       <kbd>Command</kbd>+<kbd>B</kbd> indica que el usuario debe mantener presionada la tecla <kbd>Command</kbd> y presionar la tecla <kbd>B</kbd>.
    

  •       <kbd>G</kbd><kbd>I</kbd> indica que el usuario debe presionar la tecla <kbd>G</kbd> y, luego, presionar la tecla <kbd>I</kbd>.
    

• Al describir un atajo de teclado para varios sistemas operativos, añade el sistema operativo entre corchetes después del atajo. Describe primero el acceso directo de Mac y, luego, el de Windows o Linux.

  •       **Usar:**`<kbd>Command</kbd>+<kbd>B</kbd> (Mac) or <kbd>Ctrl</kbd>+<kbd>B</kbd> (Windows/Linux)`, que se presenta como:
    
    
          <kbd>Command</kbd>+<kbd>B</kbd> (Mac) o <kbd>Ctrl</kbd>+<kbd>B</kbd> (Windows o Linux)
    

  •       **Evitar:**`<kbd>Ctrl</kbd>+<kbd>B</kbd> or <kbd>Command</kbd>+<kbd>B</kbd>`, que se presenta como:
    
    
          <kbd>Ctrl</kbd>+<kbd>B</kbd> o <kbd>Command</kbd>+<kbd>B</kbd>
    

Contenido con licencia

GitHub Docs tiene una licencia CC-BY. Si reutilizas o modificas contenido con licencia en un artículo, debes asegurarte de que la licencia sea compatible y tenga los atributos correctos.

No crees elementos reutilizables para las atribuciones de licencias. Debemos usar la licencia exacta correspondiente a un proyecto, por lo que cualquier atribución debe estar escrita con precisión en los artículos en los que aparece.

Si no estás seguro de la legalidad de reutilizar algún contenido, ponte en contacto con el servicio jurídico. Si vas a agregar contenido con una licencia que no se muestra, debes recibir una revisión de legalidad antes de poder publicar el contenido.

Atribución de contenido con licencia MIT

Si reutilizamos o modificamos contenido bajo una licencia MIT, debemos atribuir la licencia MIT allí donde aparezca el contenido.

Al final del artículo que contiene contenido con licencia MIT

• Crea un encabezado titulado Legal notice.
• Atribuye la procedencia del contenido y que tiene la licencia MIT. Incluye un vínculo al proyecto.
• Pega el texto completo de la licencia MIT del proyecto objeto de atribución en un bloque de código.

Ejemplo de atribución de licencias MIT

Este texto es solo un ejemplo. Usa siempre el texto de licencia del proyecto objeto de atribución.

## Legal notice

Portions have been adapted from [PROJECT](/LINK/TO/PROJECT) under the MIT license:

```
MIT License

Copyright YEAR COPYRIGHT-HOLDER

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
```

Saltos de línea

Con texto sin formato, usa saltos de línea para separar los párrafos del origen (dos saltos de línea consecutivos), en lugar de crear espacio visual en el origen. Evita saltos de línea innecesarios, especialmente en las listas.

Vínculos

Los vínculos se usan para conectar a personas a información adicional y avanzar a través de tareas que requieren leer varios artículos.

          **Modera la cantidad de vínculos.** Incluir demasiados vínculos puede distraer el contenido principal o robar la atención del lector. Todos los enlaces deben considerarse en el contexto del recorrido del usuario: ¿por qué podríamos enviar a alguien a este enlace y cómo podemos guiarlos de regreso para completar su tarea?

Antes de agregar un vínculo, decide si alguien debe visitar el vínculo para comprender el contenido o tener éxito con GitHub.

• Si el vínculo no es necesario, quítalo.
• Si el vínculo está relacionado con el tema principal de un artículo y permite a alguien continuar aprendiendo, pero no es necesario completar la tarea, considera la posibilidad de mover el vínculo al final del artículo como lectura adicional.
• Si el vínculo lleva a alguien al siguiente paso de un proceso, incluye el vínculo en una sección de pasos siguientes al final del artículo.
• Si el vínculo proporciona información que puede ser fundamental para completar una tarea o solucionar problemas de un paso, incluye el vínculo en el cuerpo principal del artículo.

Los vínculos deben ser coherentes, accesibles para tantas personas como sea posible, traducibles y claros. Las personas deben saber a dónde conduce un vínculo y cómo se relaciona con lo que deben lograr.

Algunos procedimientos recomendados para el uso de vínculos:

• Los vínculos deben ser significativos y aportar un gran valor al recorrido del usuario. Vincula cuidadosamente.
• No repitas el mismo vínculo más de una vez en el mismo artículo.
• Considere la posibilidad de agregar "anteriormente o más adelante en este artículo" después de un vínculo a una sección del mismo artículo.
• No incluyas el parámetro de consulta apiVersion en vínculos REST a menos que tengas que crear un vínculo a una versión de calendario específica de la documentación de REST. (Este caso no debería ser muy habitual).

Aplicar formato a vínculos

Puedes introducir vínculos con el verbo «ver» únicamente si el contexto deja claro para qué es el vínculo. Si el contexto no está claro, usa una frase u oración para introducir el vínculo, como, por ejemplo, «Para obtener más información, consulta» o «Para obtener más información sobre X, consulta Y».

Usa el título del artículo de documentación o la página web externa, como texto del vínculo. Para los vínculos que apunten a otro artículo del sitio de GitHub Docs, usa la palabra clave especial AUTOTITLE para el texto del vínculo. Consulta los detalles de la referencia de marcado de contenido.

No apliques ningún estilo a los vínculos ni los pongas entre comillas.

• Para los vínculos a otras páginas: See [AUTOTITLE](/PATH/TO/PAGE).
• Para los vínculos a secciones de otras páginas: For more information, see [AUTOTITLE](/PATH/TO/PAGE#SECTION-LINK).

No uses vínculos insertados, donde las palabras de la oración estén hipervinculadas sin ninguna palabra adicional que indique que la frase contiene un vínculo. Esto puede ser difícil de traducir y leer.

No incluyas signos de puntuación en un hipervínculo.

•           **Use:**`OAuth2 tokens can be acquired programmatically for applications that are not websites. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) and [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps).`
  

•         **Evitar:**`Read [more about OAuth2](/apps/building-integrations/setting-up-and-registering-oauth-apps/). Note that OAuth2 tokens can be [acquired programmatically](/enterprise-server@2.22/rest/reference/oauth-authorizations/#create-a-new-authorization), for applications that are not websites.`
  

Enlaces entre versiones

A veces, debes vincular desde una versión de GitHub Docs a otra. Si quieres crear un vínculo a otra versión de la misma página, debes usar la propiedad currentArticle.

Por ejemplo, la versión Free, Pro y Team de Administración de la publicación de sitios de GitHub Pages para su organización podría vincularse a la versión GitHub Enterprise Cloud del mismo artículo de la siguiente manera:

You can choose to allow or disallow the publication of GitHub Pages sites.

Organizations that use {% data variables.product.prodname_ghe_cloud %} can choose to allow publicly published sites, privately published sites, both, or neither. For more information, see [the {% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/{{ currentArticle }}).

Para crear un vínculo a otro artículo de otra versión, usa este formato:

For more information, see [ARTICLE TITLE](/) in the VERSION documentation.

Para crear un vínculo al mismo artículo de otra versión, usa este formato:

For more information, see [the VERSION documentation](/VERSION/{{ currentArticle }}).

Para crear un vínculo a una versión concreta, debes incluir la versión en la ruta de acceso (por ejemplo, /enterprise-cloud@latest/{{ currentArticle }}).

Vínculos a secciones específicas de artículos

Los vínculos a secciones específicas de artículos deben ser lo suficientemente descriptivos como para que alguien comprenda que están en el lugar correcto después de seguir un vínculo.

Para crear un vínculo a un encabezado concreto del mismo artículo, usa este formato:

For more information, see [HEADER TITLE](#HEADER-TITLE), later in this article.

Los vínculos de sección de la misma página no funcionan con AUTOTITLE. En su lugar, escribe el texto de encabezado completo.

Para crear un vínculo a un encabezado concreto de otro artículo, usa este formato:

For more information, see [AUTOTITLE](PATH-TO-ARTICLE#HEADER-TITLE).

Para crear un vínculo a dos o más encabezados concretos de otro artículo, usa este formato:

For more information, see [HEADER-TITLE-1](PATH-TO-ARTICLE#SECTION-LINK-1) and [HEADER-TITLE-2](PATH-TO-ARTICLE#SECTION-LINK-2) in "ARTICLE-TITLE."

Vínculos a una herramienta concreta

Si vinculas el contenido con una herramienta específica seleccionada, asegúrate que quede claro que el vínculo será para una herramienta específica, incluso si alguien no interactúa con la pestaña del conmutador de herramientas del artículo.

For more information, see the TOOLNAME documentation in [ARTICLE TITLE](/PATH/TO/ARTICLE?tool=TOOLNAME).

Vínculos a rutas de aprendizaje

Usa este formato para crear un vínculo a una ruta de aprendizaje.

For more information, follow the [LEARNING PATH TITLE](/) learning path.

Vínculos a recursos externos

Al vincular a un sitio externo, elige el recurso más útil para el contexto del vínculo. Puedes vincular un sitio completo si es una referencia general o una página específica si fuera más útil.

No es necesario crear un vínculo al sitio web de un producto externo cuando mencionamos un producto externo.

Para vínculos a una página externa (cualquier sitio web que no esté administrado por GitHub), escriba el título de la página completa y el sitio de destino. No coloques el vínculo entre comillas.

•           **Use:**`See [PAGE-TITLE](https://some-docs.com/PATH/TO/PAGE) in the XYZ documentation.`
  

•         **Evitar:**`See [PAGE-TITLE](https://some-docs.com/PATH/TO/PAGE).`
  

•         **Evitar:**`See [the OTHER WEBSITE](https://some-docs.com/PATH/TO/PAGE).`
  

Adición de anclajes para conservar vínculos

Si sabe que hay vínculos a una sección específica de un artículo, puede añadir un anclaje a la sección para conservar el vínculo. Por ejemplo, si un recurso externo se vincula a una sección específica de un artículo, podría agregar un anclaje para que el vínculo dirija a la sección correcta, incluso si cambia el título de la sección.

Usa este formato para las anclas de enlace. El nombre del anclaje debe ser el nombre de sección que se quiere conservar. Use un comentario HTML para explicar por qué va a añadir el anclaje.

<!-- Anchor to maintain the current example link. -->
<a name="SECTION-TITLE-THAT-MIGHT-CHANGE"></a>

Listas

Escribe en mayúscula la primera letra de cada línea de una lista. Usa puntos al final de las líneas de una lista solo si la línea contiene una oración completa.

Al escribir una lista de elementos que constan de texto principal y secundario, como un term y su definición, usa un delimitador de dos puntos. El texto secundario debe escribirse en mayúsculas como si fuera el principio de la línea. Por ejemplo:

•         `foo`: Algo que proporciona bar.
  

•         `bar`: Algo proporcionado por foo.
  

Aplicación de formato a listas sin ordenar:

• Si el orden de los elementos de la lista no es importante, ordénalos alfabéticamente.
• Si el orden es importante, ordena la lista por la importancia para el lector (por ejemplo, pasa de la audiencia y aplicabilidad más generales a un público más especializado).
• Usa asteriscos (*) para elementos de lista.

Al introducir una lista, evite las frases cortas e inespecíficas que utilicen términos como "los siguientes" o "estos", difíciles de localizar sin contexto. En su lugar, cree una frase descriptiva que transmita claramente el asunto de la lista, pero permite que la lista se escale o cambie sin tener que actualizar la descripción.

          **Use:**

• Si desea una introducción a GitHub, consulte los siguientes artículos:

• En estos países se admite la autenticación por SMS:

          **Evitar:**
  

• Existen varios artículos que ofrecen una introducción a GitHub. Vea lo siguiente:

• La autenticación por SMS es compatible en 50 países. Entre ellas se incluyen las siguientes:

Instrucciones de permisos y llamadas de producto

Usa instrucciones de permisos y llamadas de producto para comunicar las tareas que requieren roles o productos específicos para completarse.

•         [
          **Declaraciones de permisos**](/contributing/style-guide-and-content-model/contents-of-a-github-docs-article#permissions-statements): el rol necesario para realizar una acción o tarea descrita en el artículo. Ejemplo: "Propietarios de empresas".
  

•         [
          **Llamada de producto**](/contributing/style-guide-and-content-model/contents-of-a-github-docs-article#product-callout): el producto o los productos necesarios para realizar una acción o realizar una tarea descrita en el artículo. Ejemplo: "Cuentas empresariales y de organización con una suscripción a Copilot Business."
  

Juntas, las instrucciones de permisos y las llamadas de producto indican a los lectores que pueden usar la característica que se describe en un artículo.

Directrices para crear llamadas de producto escaneables

Definición de permisos frente a requisitos de producto

Ten en cuenta qué información pertenece a una declaración de permiso o un anuncio de producto.

Por ejemplo, al crear permisos y anuncios de producto para el artículo Administración de directivas y características para GitHub Copilot en su organización, la declaración de permisos podría responder a la pregunta "¿Qué rol puede administrar políticas y características para GitHub Copilot en una organización?" Y la llamada de producto respondería a "¿Qué suscripciones de Copilot necesitan los usuarios para administrar las directivas y características de Copilot para una organización?"

Céntrate en información clave, no explicaciones

Las declaraciones de permisos y las menciones de producto necesitan comunicar quién puede realizar una tarea y qué producto es necesario. No es necesario explicar por qué se requiere un rol o producto.

Si se aplican varios roles o productos a una instrucción de permiso o a una llamada de producto, dales formato mediante una lista desordenada. Puedes introducir instrucciones de permisos complejas y llamadas de producto con una frase, pero siempre intenta usar tan pocas palabras como sea necesario para comunicar quién puede hacer lo que trata el artículo.

Utilice enlaces en línea

Puedes usar vínculos insertados para proporcionar más información sobre un rol o producto. El texto vinculado debe coincidir con el destino del vínculo para que quede claro a dónde va a conducir el siguiente vínculo.

Marcadores de posición

Estiliza cualquier texto de marcador de posición en mayúsculas. Si un marcador de posición se compone de varias palabras, conecta las palabras con guiones (kebab-case). Si usas un marcador de posición, explica con qué se podría reemplazar. Esto ayuda a las personas a modificar ejemplos para adaptarlos a sus necesidades y ayuda a identificar marcadores de posición para las personas que usan tecnología de asistencia.

          **Use:**

• En el ejemplo siguiente, reemplaza YOUR-REPOSITORY por el nombre de tu repositorio. git init YOUR-REPOSITORY

• Haz clic en Add USERNAME (Agregar NOMBRE DE USUARIO). Donde USERNAME es el nombre de usuario de la persona que deseas agregar.

          **Evitar:**
  

• git init your repository

• git init <your-repository>

• Haz clic en Add username (Agregar nombre de usuario).

Pasos de procedimientos

Los procedimientos proporcionan a los lectores un conjunto de pasos secuenciales que se deben seguir para completar una tarea. Usa siempre listas numeradas para los procedimientos. Proporciona a los lectores todos los requisitos o información conceptual que necesitarán para completar la tarea antes de presentar el procedimiento, en lugar de incluirlo dentro de un paso específico.

Cada paso debe incluir una acción. También puedes optar por indicar si un paso es opcional, explicar el motivo o resultado de ese paso, y orientar al lector describiendo la ubicación de la acción antes de guiarlo para completar la acción.

Usa un orden coherente para presentar información dentro de cada paso.

1. Si el paso es opcional, indícalo primero.

2. Cuando sea necesario para mayor claridad, o para enfatizar la gravedad de una acción destructiva o confusa, explica el motivo o resultado del paso.

3. Describe la ubicación en la que el usuario encontrará la acción.

4. Acción

          **Usar:** Opcionalmente, para `REASON`, en `LOCATION`, realizar `ACTION`.
   

Ejemplos:

• Haga clic en Información de pago.
• En el nombre de la organización, haga clic en Configuración.
• Para confirmar el cambio, haga clic en Quitar tarjeta de crédito.
• Opcionalmente, para ver los detalles del plan, haga clic en Mostrar detalles.
• En "GitHub Sponsors", a la derecha del colaborador de código abierto patrocinado, haz clic en junto al importe patrocinado y, a continuación, haz clic en Cambiar nivel.

Nombres de producto

Usa los nombres de productos completos. No abrevies o acortes los nombres de productos a menos que estés reproduciendo directamente contenido del producto (por ejemplo, texto de interfaz de usuario o respuestas de API). Los nombres de los productos nunca expresan posesión.

Usa variables de nombre de producto para representar nombres de productos: no escribas nombres de productos en texto sin formato. Así se facilita la implementación de los cambios en los nombres de productos en todo el sitio y se evitan errores tipográficos en nuestros nombres de productos. Para obtener más información sobre las variables de nombre de producto, consulta "Elementos reutilizables y variables" en este documento y el directorio de datos del repositorio github/docs.

Los nombres de productos siempre están en singular. * Uso: GitHub Actions ayuda a automatizar tus flujos de trabajo de desarrollo de software. * Evitar: GitHub Actions te ayudan a automatizar tus flujos de trabajo de desarrollo de software.

Ten cuidado de distinguir entre nombres de producto y funciones de producto. Las funciones de producto siempre se escriben en minúscula.

No escribas con mayúscula funciones que se usan habitualmente, como solicitudes de incorporación de cambios, temas o problemas.

Convenciones específicas del producto

En esta sección se describen convenciones adicionales específicas de los productos de GitHub.

GitHub Actions

Elementos reutilizables para acciones de primera entidad

En los ejemplos de código que usan acciones de primera entidad se deben emplear los elementos reutilizables respectivos para esa acción. De esta forma, las actualizaciones de la versión de acción (por ejemplo, de v1 a v2) son más fáciles de administrar para productos como GitHub Enterprise Server, que podrían no tener la misma versión de acción disponible hasta un lanzamiento futuro de GitHub Enterprise Server.

Las acciones reutilizables se encuentran en /data/reusables/actions/ y tienen un nombre de archivo similar a action-<action_name>.md

Por ejemplo, para usar la acción actions/checkout en un ejemplo, usa su elemento reutilizable:

steps:
  - name: Checkout
    uses: actions/checkout@v5

Para los fines de GitHub Docs, una acción de primer orden es cualquier acción que tiene el prefijo actions/, github/ o octo-org/. Por ejemplo, esta sería una acción de terceros:

steps:
  - uses: actions/checkout@v5

Declinaciones de responsabilidades de acciones de terceros

Los ejemplos de código que usan acciones de terceros deben incluir la siguiente declinación de responsabilidades como parte del bloque de código:

# This workflow uses actions that are not certified by GitHub.
# They are provided by a third-party and are governed by
# separate terms of service, privacy policy, and support
# documentation.

Para insertar esta declinación de responsabilidades, usa el elemento reutilizable {% data reusables.actions.actions-not-certified-by-github-comment %}.

Para los fines de GitHub Docs, una acción de terceros es cualquier acción que no tiene el prefijo actions/, github/ o octo-org/. Por ejemplo, esta sería una acción de terceros:

steps:
  - uses: actions/checkout@main

Este es un ejemplo de una acción de terceros:

steps:
    - uses: google-github-actions/setup-gcloud@1bee7de035d65ec5da40a31f8589e240eba8fde5

Ejemplos:

• Consulta el bloque de código en Publicación en registros de paquetes.

Anclaje de los números de versión a SHA

Los ejemplos de código que usan acciones de terceros siempre deben anclarse a un SHA de confirmación de longitud completa, y no al número de versión o la rama:

steps:
    - uses: google-github-actions/setup-gcloud@1bee7de035d65ec5da40a31f8589e240eba8fde5

Para los fines de GitHub Docs, una acción de terceros es cualquier acción que no tiene uno de los siguientes prefijos: actions/, github/ y octo-org/. Por ejemplo, esta sería una acción de terceros:

steps:
  - uses: actions/javascript-action@main

Para más información, consulta Uso de SHA.

Codespaces

Al hacer referencia al producto Codespaces, incluye siempre "GitHub", excepto en estas circunstancias:

• En el texto preliminar de shortTitle.
• En los subtítulos de un artículo, si "Codespaces" ya se ha utilizado en cualquier parte del artículo antes del subtítulo.

Variables: {% data variables.product.prodname_github_codespaces %} ("GitHub Codespaces") y {% data variables.product.prodname_codespaces %} ("Codespaces").

Al hacer referencia a instancias de entornos de trabajo remoto creados con esta tecnología, usa "codespaces" (la c en minúsculas). Por ejemplo, "eliminar tu espacio de código" o "listar tus espacios de código".

Usa siempre "dev container" (o, cuando sea necesaria una aclaración, su forma más larga "development container") y no "devcontainer" (una palabra), excepto en los nombres de archivo y ruta de acceso. La forma de una sola palabra podría considerarse una marca, algo que queremos evitar, y además buscamos ser coherentes con la forma de dos palabras utilizada en la documentación Visual Studio Code.

Usa "development container configuration files" para hacer referencia a todos los archivos del directorio .devcontainer (más .devcontainer.json si se usa en lugar de devcontainer.json en el directorio .devcontainer). No hagas referencia a ellos como "development container files" o "devcontainer files" para evitar que se tome como referencia a archivos devcontainer.json. "Development container configuration files" hace referencia a todos los archivos que se pueden usar para configurar un contenedor de desarrollo, incluidos los archivos Dockerfile y compose.yaml. No utilices "el archivo de configuración del contenedor de desarrollo" cuando te refieras específicamente a un archivo devcontainer.json. En su lugar, haz referencia a este archivo por su nombre.

GitHub Advanced Security productos (GHAS)

Usa los términos licenses y active committers cuando hagas referencia a la facturación de GitHub Advanced Security.

Se ha usado el término seats para describir el número de cuentas que pueden usar GitHub Advanced Security en una empresa. Es posible confundirse con el término seats, por lo que eliminamos este término de GitHub.com en otoño de 2022 y las versiones a partir de GHES 3.7 no lo utilizan.

Personal access tokens

GitHub tiene dos tipos de personal access tokens:

• Fine-grained personal access tokens: ofrecen control pormenorizado sobre el acceso y los permisos del repositorio.
• Personal access token (classic): usan ámbitos y conceden acceso a todos los repositorios a los que el propietario del token puede acceder.

Debes usar variables para hacer referencia a estos tipos de tokens, así como a personal access tokens en general:

• Usa {% data variables.product.pat_generic %} o {% data variables.product.pat_generic_caps %} para hacer referencia a personal access token en general. Usa {% data variables.product.pat_generic_title_case %} si la frase debe ir en formato de título ("Personal Access Token") para coincidir con el texto de la interfaz de usuario.
• Usa {% data variables.product.pat_v2 %} o {% data variables.product.pat_v2_caps %} para hacer referencia a fine-grained personal access tokens.
• Usa {% data variables.product.pat_v1 %}, {% data variables.product.pat_v1_plural %}, {% data variables.product.pat_v1_caps %} o {% data variables.product.pat_v1_caps_plural %} para hacer referencia a personal access token (classic).

Para obtener más información sobre los personal access tokens de GitHub, consulte Administración de tokens de acceso personal.

Signos de puntuación

Siga las reglas de puntuación estándar de inglés de Estados Unidos. Para más instrucciones, consulta "Puntuación" en la Guía de estilo de Microsoft.

Notas de la versión

Un conjunto de notas de la versión en GitHub Docs indica a los lectores los cambios orientados al administrador o al usuario en una versión con control de versiones de un producto como GitHub Enterprise Server (GHES). Las notas de la versión aparecen en Notas de lanzamiento.

Una buena nota de versión es una serie de frases que responden de forma secuencial a las preguntas del lector sobre el cambio. Para más información, consulta Tipo de contenido de la nota de versión.

Cada nota de versión de un conjunto describe uno de los siguientes cambios.

•         [Características](#features): comportamiento o funcionalidad completamente nuevos.
  

•         [Correcciones de seguridad](#security-fixes): correcciones de errores o comportamientos inesperados que tienen implicaciones para la seguridad.
  

•         [Correcciones de errores](#bug-fixes): correcciones de errores o comportamiento inesperado.
  

•         [Cambios](#changes): cambios importantes en el comportamiento pasado.
  

•         [Problemas conocidos](#known-issues): problemas que GitHub ha identificado, pero que no puede clasificar por orden de prioridad o no lo ha hecho aún
  

•         [Cierre](#closing-down): proceso de retirada, ya no se debe utilizar para futuros trabajos
  

•         [Retirado](#retired): final del ciclo de vida de un producto o característica
  

•         [Errata](#errata): corrección de inexactitudes en la nota de la versión o en la documentación.
  

También puedes revisar las directrices para actualizar las notas de la versión en Adición o actualización de una nota de versión y Eliminación una nota de versión.

Características

Una nota de lanzamiento para una funcionalidad resume el comportamiento completamente nuevo. Por lo general, las notas de las características solo forman parte de las versiones de actualización de características.

Escritura de notas de la versión para características

Una nota de versión de una característica responde a las siguientes preguntas:

1. ¿Se aplica a mí esta nueva funcionalidad, con mi rol o acceso?
2. ¿Qué necesidad satisface la funcionalidad?
3. ¿Cuál es la funcionalidad?
4. Si procede, ¿dónde puedo informarme mejor sobre la funcionalidad?

          _AUDIENCIA_ (**1**) puede _DESCRIPCIÓN DE LA NECESIDAD_ (**2**) por _DESCRIPCIÓN DEL USO DE LA CARACTERÍSTICA_ (**3**). Para obtener más información, consulta [_ARTICLE TITLE_](/) (**4**)

• Clasifica cada característica dentro de una sección, bajo el encabezado de características.
• Escribe en tiempo presente.
• Para reducir la repetición y las palabras innecesarias, "ahora" suele estar implícito.
• Para aclarar los actores y el impacto, evita el uso de la pasiva cuando sea posible.

Ejemplos de notas de lanzamiento de características

• Para aumentar la seguridad de la consola de administración, los administradores del sitio pueden configurar el límite de frecuencia para los intentos de inicio de sesión, así como la duración del bloqueo después de superar el límite de frecuencia. Para obtener más información, consulta Configuración de límites de velocidad.

• Los propietarios de la empresa pueden controlar dónde pueden los usuarios bifurcar repositorios. La bifurcación puede limitarse a combinaciones preestablecidas de organizaciones, la misma organización que el repositorio primaria, cuentas de usuario o en cualquier lugar. Para obtener más información, consulta Aplicación de directivas de administración de repositorios en la empresa.

• Los usuarios pueden crear archivos con diagramas geoJSON, topoJSON y STL y representar los diagramas en la interfaz web. Para más información, consulta Uso de archivos que no son de código.

Revisiones de seguridad

Una nota de versión de una corrección de seguridad resume un cambio que mitiga o impide la explotación de un problema relacionado con la seguridad en el producto. Por lo general, las notas de correcciones de seguridad solo forman parte de las versiones de revisión.

Redacción de notas de lanzamiento para correcciones de seguridad

Una nota de versión de una corrección de seguridad responde a las siguientes preguntas.

1. Si está disponible, ¿cuál es la clasificación de gravedad de vulnerabilidad de NVD con respecto a la vulnerabilidad que se ha corregido?
2. ¿Cuál es el ataque que un atacante podría lograr aprovechando la vulnerabilidad?
3. ¿Qué tipo de vulnerabilidad es aprovechable?
4. Si está disponible, ¿cuál es el identificador CVE de la vulnerabilidad, pendiente o activo?
5. ¿Alguien notificó la vulnerabilidad a través del Programa de recompensas de GitHub?

          _GRAVEDAD_ (**1**): un atacante podría _DESCRIPCIÓN DEL IMPACTO_ (**2**) por _DESCRIPCIÓN DE LA VULNERABILIDAD DE SEGURIDAD_ (**3**). GitHub ha solicitado el identificador CVE [_CVE-####-#####_](/) (**4**) para esta vulnerabilidad, que se notificó mediante el [Programa de recompensas de GitHub](https://bounty.github.com) (**5**).

Ejemplos de notas de lanzamiento para correcciones de seguridad

•         **MEDIO**: un atacante podría provocar un agotamiento ilimitado de recursos en la instancia al realizar solicitudes paralelas a la API REST de Markdown. Para mitigar este problema, GitHub ha actualizado [CommonMarker](https://github.com/gjtorikian/commonmarker). GitHub ha solicitado el identificador CVE [CVE-2022-39209](https://nvd.nist.gov/vuln/detail/CVE-2022-39209) para esta vulnerabilidad.
  

•         **MEDIO**: un atacante podría insertar vínculos peligrosos en la interfaz de usuario web de la instancia porque los vínculos de vista previa de solicitudes de incorporación de cambios no sanearon correctamente las direcciones URL. Esta vulnerabilidad se notificó mediante el [Programa de recompensas de GitHub](https://bounty.github.com).
  

Actualizaciones de imágenes base y paquetes

También se incluyen la imagen base y las actualizaciones de paquetes dependientes en la sección "Correcciones de seguridad", ya que estas actualizaciones suelen abordar problemas de seguridad. Consolidamos todas estas actualizaciones en la nota siguiente.

Los paquetes se han actualizado a las últimas versiones de seguridad.

Corrección de errores

Una nota de versión para la corrección de un error describe una corrección a un comportamiento indeseado o inesperado. Por lo general, las notas de corrección de errores solo forman parte de las versiones de parches.

Redacción de notas de lanzamiento para correcciones de errores

Una nota de versión de una corrección de errores responde a las siguientes preguntas:

1. ¿El comportamiento me ha afectado a mí, con mi rol o acceso?
2. ¿Qué comportamiento experimentaría el lector antes de la corrección?

          _AUDIENCIA_ (**1**) _DESCRIPCIÓN DEL COMPORTAMIENTO_ (**2**).

• Dado que el error ahora se ha corregido, escribe en tiempo pasado.
• Expresiones como "fixed a bug..." o "fixed an issue..." están implícitas y son innecesarias.
• Para reducir la repetición y las palabras innecesarias, "ahora" suele estar implícito.
• Para aclarar los actores y el impacto, evita el uso de la pasiva cuando sea posible.
• Si la nota de versión incluye un mensaje de error, debe darse formato al mensaje según las instrucciones de Mensajes de error.

Ejemplos de notas de lanzamiento para correcciones de errores

• Después de que un usuario importara un repositorio con la protección de inserción habilitada, el repositorio no se pudo visualizar inmediatamente en la vista "Cobertura de seguridad" de la información general de seguridad.

• En una instancia con GitHub Actions habilitado, un trabajo de GitHub Actions no se iniciaría si no hubiera un grupo de ejecutores coincidente disponible al momento en que el trabajo se puso inicialmente en cola, incluso si dicho grupo se volviera disponible después de que el trabajo ya estuviera en cola.

• Los comandos que los administradores del sitio ejecutaban a través de SSH en cualquiera de los nodos de instancias no se registraban en /var/log/ssh-console-audit.log.

Cambios

Una nota de lanzamiento para un cambio explica un cambio notable, pero menor, en el comportamiento actual. Las notas de los cambios responden a las siguientes preguntas:

Escritura de notas de la versión para cambios

Una nota de versión de un cambio responde a las siguientes preguntas:

1. ¿El comportamiento me ha afectado a mí, con mi rol o acceso?
2. Si el cambio resuelve o evita un problema, ¿cuál es ese problema?
3. ¿Cuál es el nuevo comportamiento?
4. Si es pertinente, ¿cuál era el comportamiento antes del cambio?

          _AUDIENCIA_ (**1**) / _DESCRIPCIÓN DEL PROBLEMA QUE RESUELVE EL CAMBIO_ (**2**) _DESCRIPCIÓN DEL NUEVO COMPORTAMIENTO_ (**3**) _DESCRIPCIÓN DEL COMPORTAMIENTO ANTERIOR_ (**4**).

• Dado que el cambio se aplica a la versión en cuestión, escribe notas para los cambios en tiempo presente.
• Para reducir la repetición y las palabras innecesarias, "ahora" suele estar implícito.
• Para aclarar los actores y el impacto, evita el uso de la pasiva cuando sea posible.
• A menudo, la audiencia está implícita.
• Si resulta útil, incluye vínculos pertinentes a GitHub Docs.

Ejemplos de notas de lanzamiento para cambios

• En una instancia con una licencia para GitHub Advanced Security, los usuarios que diseñan patrones personalizados para el análisis de secretos pueden proporcionar expresiones que deban coincidir o no coincidir, con un máximo de 2000 caracteres. Este límite ha aumentado desde los 1000 caracteres.

• Para los administradores que necesitan revisar o modificar las asignaciones de SAML, la ruta predeterminada de la salida de ghe-saml-mapping-csv -d es /data/user/tmp en lugar de /tmp. Para obtener más información, consulta Utilidades de línea de comandos.

• Para evitar problemas intermitentes con el éxito de las operaciones de Git en una instancia con varios nodos, GitHub Enterprise Server comprueba el estado del contenedor mySQL antes de intentar una consulta SQL. También se ha reducido la duración del tiempo de espera.

Problemas conocidos

Una nota de versión de un problema conocido describe un problema que GitHub ha identificado, pero al que no se puede dar prioridad o que aún no se le ha dado.

Redacción de notas de actualización sobre problemas conocidos

Una nota de la versión de un problema conocido responde a las siguientes preguntas:

1. ¿El comportamiento afecta mi rol o acceso?
2. ¿Cuáles son los mensajes de error u otros elementos reconocibles de la interfaz de usuario que aparecen?
3. ¿Debo actuar? Si es así, ¿qué debo hacer?

          _AUDIENCIA_ (**1**) _DESCRIPCIÓN DEL PROBLEMA_ (**2**) _DETALLES DEL COMPORTAMIENTO_ (**3**) _PASOS SIGUIENTES_ (**4**).

• Para aclarar los actores y el impacto, evita el uso de la pasiva cuando sea posible.
• Para reducir la repetición y las palabras innecesarias, "ahora" suele estar implícito.
• Si la nota de versión incluye un mensaje de error, debe darse formato al mensaje según las instrucciones de Mensajes de error.
• Si resulta útil, incluye vínculos pertinentes a GitHub Docs.
• Los problemas conocidos también son un tipo de contenido en GitHub Docs. Para más información, consulta Tipo de contenido de solución de problemas. Si resulta útil, escriba o vincule a contenido más detallado y contextualmente relevante en los documentos.

Ejemplos de notas de lanzamiento para problemas conocidos

• Una vez que un usuario habilita la opción para que un repositorio permita a los usuarios con acceso de lectura para crear discusiones, la característica no está habilitada.

• Después de que un administrador inicie una ejecución de configuración, No such object error puede producirse durante la fase de validación de los servicios Notebook y Viewscreen. Este error se puede omitir porque los servicios todavía se deben iniciar correctamente.

Cierre definitivo

Una nota de la versión para una característica que se va a cerrar resume un comportamiento o característica que GitHub pretende eliminar. Estas características siguen estando disponibles para su uso en producción e incluyen los SLA de soporte técnico asociados y las obligaciones de soporte técnico. Sin embargo, están en proceso de retirada y ya no se debe confiar en ellas para el trabajo futuro. El cierre es una fase de transición en la que se recomienda a los usuarios que dejen de usar la característica y se preparen para su retirada.

Redacción de notas de la versión sobre características que se van a cerrar

Las notas de la versión de una característica que se va a cerrar responden a las siguientes preguntas:

1. ¿Se aplica a mí esta funcionalidad existente, con mi rol o acceso?
2. ¿Cuál es la funcionalidad que se va a cerrar?
3. Si procede, ¿qué reemplaza la funcionalidad de cierre?
4. Si procede, ¿dónde puedo encontrar más información?

          _AUDIENCIA_ (**1**) _DESCRIPCIÓN DE LA FUNCIONALIDAD QUE SE V A CERRAR_ (**2**) _FUNCIONALIDAD DE REEMPLAZO_ (**3**) Para más información, consulta [_TÍTULO DEL ARTÍCULO_](/) (**4**).

• Las notas están en tiempo presente o en futuro para los próximos cambios. Si procede, especifique la próxima versión en la que se producirá la retirada.
• Para reducir la repetición y las palabras innecesarias, "ahora" suele estar implícito.
• Para aclarar los actores y el impacto, evita el uso de la pasiva cuando sea posible.
• Clasifica cada característica dentro de una sección, bajo el encabezado de características.

Ejemplos de notas de la versión para características que se van a cerrar

•         **Cierre**: en GitHub Enterprise Server 3.8 y versiones posteriores, para garantizar la seguridad de la instancia, los algoritmos que no sean seguros se desactivarán para las conexiones SSH con el shell administrativo.
  

• Los comentarios de confirmación, que son los que los usuarios agregan directamente a una confirmación fuera de una solicitud de incorporación de cambios, ya no aparecen en la escala de tiempo de la solicitud de incorporación de cambios. Los usuarios no han podido responder a estos comentarios ni resolverlos. La API REST de eventos de la línea de tiempo y el objeto PullRequest de la API GraphQL ya no devuelven comentarios de confirmación.

Retirado

Los productos o características retirados ya no están disponibles para clientes nuevos, no se comercializan y no se ofrece soporte técnico ni documentación. En esta fase, el producto deja de ofrecerse de manera efectiva y no se proporcionarán nuevas correcciones ni desarrollos. El único soporte técnico que se ofrece para los productos retirados puede provenir de los compromisos existentes, como los necesarios para las versiones de GitHub Enterprise Server publicadas anteriormente. La retirada marca el final oficial del ciclo de vida de un producto o característica, sin actualizaciones adicionales, correcciones de errores ni soporte técnico, lo que indica una transición completa a las herramientas o servicios más recientes.

Redacción de notas de la versión para características retiradas

Una nota de versión de una característica retirada responde a las siguientes preguntas:

1. ¿Se aplica a mí esta funcionalidad, con mi rol o acceso?
2. ¿Cuál es la funcionalidad que se retira?
3. Si procede, ¿qué reemplaza la funcionalidad retirada?
4. Si procede, ¿dónde puedo encontrar más información?

          _DESTINATARIOS_ (**1**) _DESCRIPCIÓN DE LA FUNCIONALIDAD RETIRADA_ (**2**) _FUNCIONALIDAD DE REEMPLAZO_ (**3**) Para obtener más información, consulta el artículo titulado [_TÍTULO DEL ARTÍCULO_](/) (**4**)

• Las notas se escriben en tiempo presente.
• Para reducir la repetición y las palabras innecesarias, "ahora" suele estar implícito.
• Para aclarar los actores y el impacto, evita el uso de la pasiva cuando sea posible.
• Clasifica cada característica dentro de una sección, bajo el encabezado de características.

Ejemplos de notas de lanzamiento para características retiradas

•         **Retirado**: GitHub ya no admite flujos de trabajo necesarios para GitHub Actions en GitHub Enterprise Server 3.11 y versiones posteriores. En su lugar, use los conjuntos de reglas del repositorio. Para más información, consulta [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-workflows-to-pass-before-merging).
  

Errata

La errata corrige información inexacta publicada anteriormente en las notas de la versión o en la documentación de una versión.

Redacción de erratas

La errata responde a las siguientes preguntas:

1. Si procede, ¿qué sección de las notas de la versión o del contenido de GitHub Docs resultó afectada?
2. ¿La información incorrecta se aplica a mí, teniendo en cuenta mi rol o acceso?
3. ¿Qué describía incorrectamente la nota de la versión o la documentación?
4. ¿Cuándo se publicó la errata?

          _CONTENIDO_ (**1**) indicó incorrectamente que _AUDIENCIA_ (**2**) puede _RESUMEN DE INFORMACIÓN INEXACTA_ (**3**). [Actualizado: _FECHA DE PUBLICACIÓN_**4**]

• Da formato a la fecha de publicación según las instrucciones de Adición o actualización de una nota de lanzamiento.

Ejemplo de errata

• Se indicó incorrectamente en Características que los usuarios de GitHub Advisory Database pueden ver avisos para Elixir, el administrador de paquetes Hex de Erlang y más. Esta característica no está disponible en GitHub Enterprise Server 3.7, pero lo estará en una versión futura. [Actualizado: 01/06/2023]

Adición o actualización de una nota de versión

Para indicar a los lectores que has agregado o cambiado una nota, o para indicar la fecha de publicación de la errata, anexa una marca de fecha con el formato "[Updated: YYYY-MM-DD]".

Quitar una nota de versión

Para indicar que hemos eliminado una nota de versión, agrega una sección "Errata" que detalle qué nota has quitado y (si procede) a qué versión pertenece realmente la nota eliminada. Consulta Escritura de errata.

Liberar las referencias

Al hacer referencia a una serie de versiones a partir de una versión determinada, usa "o posterior".

•         **Use:** "versión 0.41.0 o posterior"
  

•         **Evite:** "versión 0.41.0 o anterior"
  

•         **Evite:** "versión 0.41.0 o superior"
  

Elementos reutilizables y variables

Usa cadenas reutilizables para nombres individuales (por ejemplo, nombres de producto) o para oraciones o párrafos completos. Los fragmentos de oraciones y las frases no deben estar contenidos en cadenas reutilizables, ya que pueden causar problemas cuando se localiza el contenido. Para obtener más información, consulta el directorio de datos en el repositorio github/docs, Creación de contenido reutilizable y la sección Nombres de productos de este documento.

Tablas de contenido por secciones

Si una sección de un artículo usa encabezados H3 o H4 para dividir aún más el contenido y solo parte de él es de interés para un lector, puedes usar una tabla de contenido (TOC) por secciones para ayudar a los lectores a identificar la información más interesante para ellos y desplazarse hasta ella. Por ejemplo, en Streaming del registro de auditoría de su empresa las personas probablemente solo configurarán el streaming de registro de auditoría para un proveedor, por lo que la tabla de contenido por secciones en "Configuración del streaming de registro de auditoría" permite a los usuarios seleccionar su proveedor y desplazarse hasta el contenido de interés sin leer toda la sección.

No agregues una tabla de contenido por secciones si los encabezados H3 o H4 solo se usan para agrupar el contenido y toda la información podría ser de interés para un lector. Por ejemplo, en Aspectos básicos de la administración de identidades y acceso, las personas deben leer y considerar cada sección en relación con su empresa. En este artículo no se incluye una tabla de contenido por secciones, ya que los usuarios deben leer cada sección, no elegir entre ellas. La adición de una tabla de contenido por secciones también obligaría a los usuarios que usan lectores de pantalla u otra tecnología adaptable a usar el tabulador y desplazarse por más encabezados antes de encontrar lo que necesitan.

Aplicación de formato a tablas de contenido por secciones como una lista Incluye todas las subsecciones en el orden en que aparecen en el artículo y haz referencia a ellas mediante el título de encabezado completo.

Las tablas de contenido por secciones deben introducirse con una oración o párrafo que ayude a las personas a comprender cómo se organiza el contenido y seleccionar la sección de más interés para ellos. No incluyas una tabla de contenido por secciones directamente debajo de un encabezado.

Ejemplo de tablas de contenido por secciones

## Setting up the application

Set up your application according to your operating system.

* [Setting up for macOS](#setting-up-for-macOS)
* [Setting up for Windows](#setting-up-for-windows)
* [Setting up for Linux](#setting-up-for-linux)

### Setting up for macOS

TEXT

### Setting up for Windows

The application is supported for all versions of Windows, but the set up steps differ.

* [Windows 98](#windows-98)
* [Windows Vista](#windows-vista)
* [Windows 11](#windows-11)

#### Windows 98

TEXT

#### Windows Vista

TEXT

#### Windows 11

TEXT

### Setting up for Linux

TEXT

Tablas

Las tablas se agregan a los datos GitHub Docs mediante Markdown. Dado que las tablas pueden ser difíciles de leer y mantener, asegúrese de que los datos de una tabla se representan mejor en una tabla y no en otro formato, como una lista, antes de crear una tabla. Todas las filas de una tabla deben comenzar y terminar con una canalización, |.

Uso de tablas solo para presentar información tabular

Las tablas funcionan mejor para presentar datos tabulares, como información que debe compararse o valores con varios atributos. No uses tablas para listas sencillas; consulta la sección Listas de este documento.

Evite describir datos de la tabla

Los datos de una tabla y su importancia deben quedar claros en el contenido que la precede, en los encabezados de columna y (si es necesario) en los encabezados de fila. Evita descripciones innecesarias de los datos de una tabla. Si los datos de una tabla no están claros sin una descripción larga, considera si la tabla necesita encabezados de fila o si la información se comunicaría mejor de otra manera.

Por ejemplo, en Referencia de ejecutores autohospedados, se introduce una tabla que compara las características entre dos soluciones de escalado automático compatibles con la frase Each solution has certain specifics that may be important to consider. El artículo no describe ninguna de las distintas características que se comparan porque la tabla comunica claramente esa información.

•         **Usar:** "Se aplican diferentes límites de tamaño por repositorio según la versión de su GHES."
  

•         **Evitar:** "La primera fila de la tabla muestra la información para GitHub Enterprise Cloud. La segunda fila muestra la información para GitHub Enterprise Server.
  

•         **Evitar:** “La tabla a continuación muestra qué tipo de datos de migración se exportan.”
  

Uso del marcado adecuado para los encabezados de fila y columna

Las tablas en las que la primera columna describe los valores de los datos de la tabla (pero no son datos en sí) deben marcarse con encabezados de fila. Esto es importante para que la tecnología de asistencia comprenda las relaciones entre las celdas.

Por ejemplo, en la tabla siguiente, para que los valores "Yes" y "No" de la tabla tengan sentido, debes conocer tanto el encabezado de columna (rol) como el encabezado de fila (permiso).

Para agregar encabezados de fila a una tabla de Markdown, encapsula la tabla en las etiquetas Liquid {% rowheaders %} {% endrowheaders %}. Para más información sobre el uso de los encabezados de fila, consulta Uso de Markdown y Liquid en la documentación de GitHub.

Inclusión de un valor para cada celda

Cada celda de una tabla debe contener un valor.

Para las celdas sin datos, use "Ninguno" o "No disponible". No utilices "NA" o "N/A".

En el caso de las tablas con encabezados de fila, la primera celda (celda "A1") debe describir los encabezados de fila para ayudar a las personas a comprender toda la tabla. Sin embargo, si esto haría que la tabla fuera menos clara o que se agregara información redundante, puede dejar esta celda vacía. Por ejemplo, en el artículo Compilar y probar PowerShell, la primera celda podría etiquetarse como "Módulos", pero dado que cada encabezado de fila ya incluye la palabra "módulo", este encabezado repetiría información que no agrega valor descriptivo para comprender toda la tabla.

Uso de símbolos y etiquetas claros y coherentes

Para las tablas que usan símbolos:

• Rellena todas las celdas. Por ejemplo, en una tabla de permisos, no marques solo las celdas de elementos que requieren un permiso.
• Usa octiconos o SVG. No utilices emoji. Para obtener más información sobre los octiconos, consulta Uso de Markdown y Liquid en la documentación de GitHub.
• Usa una marca de verificación para los valores afirmativos ("Yes", "Required", "Supported") y una cruz para los valores negativos ("No", "Optional", "Unsupported").
• Usa aria-label para describir el significado del símbolo, no sus características visuales. Por ejemplo, "Requerido", no "Icono de marca de verificación".

Cuando los datos de tabla no sean realmente binarios (cada valor sea "Yes" o "No", por ejemplo), puede que sean necesarios valores de texto además de símbolos o en lugar de estos. Por ejemplo, en la página Acerca de la compatibilidad con GitHub, algunas características se marcan como "Disponible para comprar".

Uso de notas al pie con moderación

Consulta Notas al pie.

Alineación del contenido de la tabla de forma coherente

Todas las columnas de una tabla deben estar alineadas a la izquierda, excepto las columnas que solo contienen octiconos que deben estar alineadas centralmente. Si una columna contiene texto y octiconos, usa la alineación en el centro.

El contenido de la tabla se alinea a la izquierda de forma predeterminada. Usa el formato de tabla Markdown, dos puntos (:) a la derecha o a la izquierda de los guiones de la fila de encabezado, para especificar la alineación de cada columna. Para más información, lee Organizar la información en tablas.

En el ejemplo siguiente se muestra parte de una tabla de Referencia de opciones de Dependabot.

La tabla se genera con la siguiente sintaxis de alineación.

| Option              | Required | Security Updates | Version Updates | Description                    |
|---------------------|:--------:|:----------------:|:---------------:|--------------------------------|
| `package-ecosystem` |{% octicon "check" aria-label="Supported" %}|{% octicon "x" aria-label="Not supported" %}|{% octicon "check" aria-label="Supported" %}| Package manager to use         |
| `directory`         |{% octicon "check" aria-label="Supported" %}|{% octicon "x" aria-label="Not supported" %}|{% octicon "check" aria-label="Supported" %}| Location of package manifests  |
| `schedule.interval` |{% octicon "check" aria-label="Supported" %}|{% octicon "x" aria-label="Not supported" %}|{% octicon "check" aria-label="Supported" %}| How often to check for updates |

Títulos

Use mayúscula inicial en las oraciones de los títulos.

Títulos cortos

Usamos títulos cortos para rellenar el panel de navegación lateral. Dado que los títulos cortos aparecen en la navegación de la barra lateral, pueden usar el contexto para transmitir el significado y ser un poco menos precisos que los títulos completos. El objetivo de los títulos cortos consiste en ayudar a las personas a encontrar el contenido que buscan sin tener elementos de navegación de barra lateral demasiado largos. Los títulos cortos facilitan la comprensión contextual de un artículo y se ajustan a los siguientes estándares.

• Los títulos cortos tienen una longitud de 2 a 3 palabras.
  • Para las categorías, los títulos cortos deben tener menos de 27 caracteres.
  • Para los temas de mapa, los títulos cortos deben tener menos de 30 caracteres.
  • En el caso de los artículos, los títulos cortos deben tener menos de 31 caracteres e idealmente entre 20 y 25 caracteres.
• Los títulos cortos usan la forma base de los verbos en lugar de gerundios. * Usa: "Configurar notificaciones" en lugar de "Configurando notificaciones".
• Los títulos cortos para categorías, temas de mapa y artículos pueden omitir los nombres de producto y características si está claro con qué producto o característica se relacionan. * Use: "Configurar notificaciones" como título corto para Configuración de notificaciones para alertas de Dependabot, ya que el artículo se encuentra en el tema de mapa "Dependabot alerts".
• Los títulos cortos no introducen palabras nuevas que no están en el título completo.
• Los títulos cortos deben ser paralelos a los títulos cortos de contenidos similares. * Utilice: "Organizaciones y equipos" y "Cuentas empresariales" * Evita: "Organizaciones y equipos" y "Administración de cuentas empresariales"

Escribir títulos cortos puede ser difícil. Para obtener títulos cortos que se ajusten al recuento de caracteres, considera el título corto en su contexto. Quita las palabras repetidas si es posible y cualquier nombre de producto o característica que se encuentre en el tema o categoría del mapa al que pertenece el contenido.

Contenido de la directiva de sitio

No use variables o reutilizables en el contenido de la política de sitio. Los artículos de directivas del sitio son documentos legales y deben tener una fuente legible para humanos.

De lo contrario, el contenido de la directiva del sitio usa el mismo estilo y modelos de contenido que el resto de GitHub Docs.

Elementos de la interfaz de usuario

Negrita

Usa negrita para describir los elementos de la interfaz de usuario con los que se puede interactuar.

• En la barra lateral de la izquierda, haga clic en Billing.
• Mira en el cuadro de combinación en la parte inferior de la pestaña Conversación de la solicitud de incorporación de cambios.
• Junto a Título, agrega una etiqueta descriptiva para la nueva clave.

Nombres de ramas

Usa el formato de código en los nombres de rama.

• main
• USERNAME.github.io

Botones

Usa la negrita para los nombres de botón y, siempre que sea posible, omite la palabra "button". Para describir el uso de un botón, escribe “Click”, no "push" o "pulsar". * Uso: Haga clic en Pull request. * Evite: Pulse el botón Extraer solicitud.

Casillas

Usa la negrita para los nombres de casilla y omite la palabra "checkbox". Para describir la activación o desactivación de una casilla, usa "select" o "deselect". * Usar: Selecciona Habilitar para todos los nuevos repositorios. * Evitar: No marcar la casilla “Habilitar para todos los nuevos repositorios”.

Texto dinámico

Usa letras mayúsculas para indicar texto que cambia en la interfaz de usuario o que el usuario debe proporcionar en un comando o fragmento de código. * Use: Haga clic en Agregar USERNAME a REPONAME.

Listas y elementos de lista

Usa la negrita para las listas y los elementos de lista en los que se puede hacer clic. Para describir la interacción con una lista, como un menú desplegable o un elemento de interfaz de usuario que se expande, independientemente de si el nombre de la lista es una palabra o un octicon, escribe "select". Para describir cómo elegir un elemento de lista, escribe "click". * Usar: Seleccione el menú desplegable de Direcciones de correo electrónico de respaldo y haga clic en Solo permitir correo electrónico principal. * Evitar: Haz clic en el menú desplegable "Direcciones de correo electrónico de respaldo" y selecciona Permitir solo correo electrónico principal.

Ubicación

Según las instrucciones de WCAG, debemos describir los elementos por nombre y no simplemente por apariencia o ubicación. La Guía de estilo de Microsoft ofrece instrucciones específicas para frases direccionales, con énfasis en su uso en la documentación.

•         [Encima](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/above) o [debajo](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/b/below)
  

•         [Superior izquierda, superior derecha](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/u/upper-left-upper-right)
  

•         [Inferior izquierda, inferior derecha](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/l/lower-left-lower-right)
  

• Al lado, abajo o arriba de la página, a la izquierda o a la derecha de la página

Paneles

Cuando sea posible, evita hacer referencia a paneles. En su lugar, describe lo que el usuario debe hacer. * Uso: Haz clic en Ver gráficos y diagramas para tu repositorio, luego selecciona el periodo de tiempo que deseas ver del menú desplegable. * Evitar: Haz clic en Ver gráficos y diagramas para abrir el panel de tu repositorio seleccionado, luego selecciona el periodo de tiempo que deseas ver desde el menú desplegable.

Si necesitas hacer referencia a un panel para describir un cambio en la interfaz de usuario o explicar cómo interactuar con la interfaz de usuario, usa el formato del texto de la interfaz de usuario para el nombre del panel. Incluye solo la palabra "panel" si agrega claridad o si el panel no tiene ningún nombre en la interfaz de usuario.

•         **Uso:** En el panel "Cobertura de seguridad", seleccione **Habilitar** o **Deshabilitar**.
  

•         **Uso:** En el panel, seleccione **Habilitar** o **Deshabilitar**.
  

Botones de radio

Usa la negrita para las etiquetas del botón de radio y omite las palabras "radio button" o cualquier otro descriptor. Para describir el uso de un botón de radio, escribe "select".

Nombres de repositorio

Aplicar estilo a los nombres de repositorio en la fuente monoespaciada mediante acentos versos. Proporcione un vínculo a los repositorios cuando se espera que los usuarios naveguen a ellos. * Use: Para más información, consulte el repositorio github/docs.

Elementos con capacidad de respuesta

Solo documentamos los estados con capacidad de respuesta de los elementos de la UI cuando crean ambigüedad o confusión. Si una tarea no está clara debido a un elemento de la UI con capacidad de respuesta, describe la interacción que debe hacer alguien para lograr el objetivo de la tarea. No solo describa el estado visual del elemento de la UI.

•         **Uso:** haz clic en **Seguridad**. Si "Seguridad" no está visible, haz clic en **⋮** para expandir el menú del repositorio.
  

Texto de la interfaz de usuario

Al hacer referencia a texto de la interfaz de usuario, reproduce el texto con exactitud. Usa comillas para el texto de la interfaz de usuario con el que no se puede interactuar. Coloca las comas fuera de las comillas.

•         **Usar:** En "lista de permitidos de IP", haga clic en **Editar**.
  

Más recursos

Guía de estilo de Microsoft: * Formato del texto en las instrucciones

Vídeos

Puedes agregar vídeos para reforzar la información basada en texto, pero los vídeos nunca deben reemplazar el contenido escrito. Los vídeos son inaccesibles para algunos usuarios y también son difíciles de encontrar mediante la búsqueda.

Los vídeos del sitio web de GitHub Docs deben estar bien producidos y contener menos barreras para las personas con discapacidad, y ajustarse a nuestro modelo de contenidos para vídeos. Para más información, consulta Acerca del uso de vídeos en GitHub Docs.

Voz y tono

Usa un lenguaje claro y sencillo que sea accesible para una amplia variedad de lectores. Tu escritura debe demostrar autenticidad, empatía y seguridad.

Escribe para tu audiencia: algo de jerga y términos técnicos son necesarios, pero no des por sentado que todos los lectores tienen el mismo nivel de conocimientos técnicos.

Use la voz activa siempre que sea posible. Las voces pasivas son aceptables cuando es necesario resaltar el objeto de una acción.

Somos una comunidad global de desarrolladores. Evita los giros idiomáticos y el argot propios de una región o país concretos.

Para más información sobre cómo escribir contenido accesible, consulta "La voz de la marca Microsoft: Ante todo, sencilla y humana y "10 sugerencias principales para el estilo y la voz de Microsoft".

Elección de palabras y terminología

Para instrucciones generales y términos específicos de GitHub, consulta nuestro Glosario. Para instrucciones más detalladas, consulta la "lista de palabras de la A a la Z" en la guía de estilo de Microsoft.

Abreviaturas

Deletrea las palabras excepto cuando te refieras a una palabra acortada explícitamente en el propio producto. * Usar: Repositorio. * Evite: Repo. * Usar: Administrador, personas con permisos de administrador. * Evitar: administradores.

No uses símbolos ni octiconos que no se empleen en la interfaz de usuario de GitHub. * Usar: Haz clic en Archivo y, luego, en Editar. * Evitar: Haz clic en Archivo > Editar.

Cuentas

Nombres y cuentas de productos

Para evitar ambigüedades y confusiones, no uses los nombres de los productos como adjetivos para describir las cuentas de ninguno de nuestros productos. En su lugar, aclara el tipo de cuenta y elige una redacción más clara que evite confundir cuentas y productos. Al hablar de cuentas, solo haz referencia al nombre del producto cuando sea necesario para eliminar la ambigüedad entre los productos. Para más información sobre los tipos de cuentas disponibles en los productos de GitHub, consulta Tipos de cuentas de GitHub. * Use: Su organización en GitHub Enterprise Cloud * Evite: Su cuenta de GitHub Enterprise Cloud * Evite: Su organización de GitHub Enterprise Server * Uso: Puedes resaltar tu trabajo en GitHub Enterprise Server enviando los recuentos de contribuciones a tu perfil de GitHub.com.

Cuentas de individuos de GitHub

Nos referimos a cuentas en las que un individuo inicia sesión de varias maneras según el contexto.

A menos que el contenido trate sobre la administración de un producto empresarial, describe la cuenta de un individuo de GitHub como "personal account". Así se crea coherencia con la interfaz de usuario y se evita que los lectores se confundan viendo dos términos que significan lo mismo.

•         **Usar:** Gestionar recordatorios programados para tu cuenta personal.
  

•         **Evite:** Administración de recordatorios programados para su cuenta de usuario.
  

Cuentas para productos empresariales

Con los productos empresariales de GitHub, los administradores administran una cuenta empresarial. Una cuenta empresarial puede ser propietaria de varias organizaciones y las cuentas de usuario de las personas pueden ser miembros de las organizaciones. Para más información, consulta el artículo "Roles en una empresa" de cada producto.

•         [GitHub Enterprise Cloud](/enterprise-cloud@latest/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise)
  

•           [GitHub Enterprise Server](/enterprise-server@latest/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise)
  

Si el lector administra una cuenta de empresa y describes las cuentas de las personas que este administra, usa "user account". Esto se aplica a los siguientes productos.

• GitHub Enterprise Cloud con Enterprise Managed Users * Uso: Con Enterprise Managed Users, puedes crear y gestionar cuentas de usuario para los miembros de tu empresa. * Evitar: Con Enterprise Managed Users, puedes crear y gestionar las cuentas personales de los miembros de tu empresa.
• GitHub Enterprise Server * Usar: Si necesita hacerse cargo temporalmente de una cuenta de usuario… * Evitar: Si necesitas tomar temporalmente el control de una cuenta personal…

La siguiente documentación debe hacer referencia a "cuentas de usuario".

• El producto Documentación para administradores empresariales.
• Documentación de facturación específica de la empresa, como Facturación de GitHub Enterprise.
• Contenido de otros productos destinado a una audiencia administrativa, como Procedimientos recomendados para proteger las cuentas en el producto "Codificación segura" o Configuración de una versión de prueba de GitHub Enterprise Cloud en el producto "Introducción"
• Contenido de API específico de la empresa, como la documentación de referencia de la API REST de Puntos de conexión de la API REST para la administración de GitHub Enterprise

En el caso de las empresas de GitHub Enterprise Cloud que no usan Enterprise Managed Users, utiliza "cuenta personal" al describir a los miembros de organizaciones propiedad de la empresa.

•         **Uso:** Si configuras SAML SSO, los miembros de tu organización seguirán iniciando sesión en sus cuentas personales en GitHub.com.
  

•         **Evite lo siguiente:** Si configura SSO de SAML, los miembros de su organización seguirán iniciando sesión en sus cuentas de usuario en GitHub.com.
  

La documentación que describe GitHub Enterprise Cloud sin Enterprise Managed Users suele estar en la categoría Administrar el inicio de sesión único de SAML para tu organización.

Cuentas de personas para otros servicios

Cuando se describa la cuenta de una persona para un servicio distinto de GitHub, como un proveedor de integración o autenticación, usa "user account".

Acrónimos

Escribe los acrónimos la primera vez que se usan en un artículo, excepto en títulos o encabezados.

Aplicaciones

Usa "app" o "application" en contenido general. * Usar: Publica y lista tu aplicación en GitHub Marketplace.

Usa "app" al hacer referencia a OAuth apps ya que no son un producto. * Use: Registrar una OAuth app. * Evite: Registrar una OAuth App.

Usa "App" al hacer referencia a GitHub Apps ya que se trata de un producto. * Use: Registrar una GitHub App.

Las GitHub Apps y las OAuth apps constan de dos partes: el registro de la aplicación y el código que hace que la aplicación haga algo.

• Para hacer referencia solo a la configuración de GitHub App en la interfaz de usuario de GitHub, usa terminología como "register" y "GitHub App registration". * Use: Registrar una GitHub App. * Use: Actualizar un registro de GitHub App. * Evite: Crear una GitHub App. * Evite: Modificar una GitHub App.

• Para hacer referencia solo al código de la aplicación, usa terminología como "code for your app" o "your app's code". * Utiliza: el código para tu aplicación. * Use: código para la GitHub App. * Usar: el código de tu aplicación. * Evite: Su GitHub App. * Evite: Su OAuth app.

• Para hacer referencia a la aplicación entera de forma colectiva (registro y código), usa GitHub App o OAuth app.

Las GitHub Apps se pueden instalar en cuentas de usuario o de organización. Para hacer referencia a una instalación de la aplicación, usa "GitHub App installation" en lugar de "GitHub App".

Moneda

Al hacer referencia a dólares, centavos, cantidades de moneda o usar el signo $, asegúrate de que la moneda usada se define incluso si la cantidad es cero. Usa la denominación de la moneda según la norma ISO y el código de moneda según la norma ISO siempre que sea posible.

Usa minúsculas para los nombres de moneda, pero escribe en mayúsculas la referencia al país o región. * Uso de: dólar estadounidense. * Evite: dólar de EE. UU., dólar $USD

Usa mayúsculas para los códigos de moneda. * Utilizado en: USD.

Si solo hay una referencia en un artículo, usa el nombre de moneda sin el símbolo $ que precede al importe. * Usar:10 US dollars en el caso de una sola referencia a la moneda.

Cuando un artículo contenga varias referencias a la misma moneda, asegúrate de que la primera referencia utiliza el nombre de la moneda sin el signo $ delante del importe y de que incluye el código de la moneda entre paréntesis a continuación del nombre de la moneda.

Para las referencias posteriores a la moneda en un artículo o cuando proceda (por ejemplo, cuando el espacio sea un factor a tener en cuenta, o cuando se presenten varias cantidades en una tabla o lista), incluye el signo $ delante de la cantidad y usa el código de moneda de la norma ISO a continuación de la cantidad. * Usar:10 US dollars (USD) para la primera referencia y $0.25 USD para las referencias posteriores. * Evitar:$10 US dollars (USD), USD$0.25.

Cuando la primera referencia sean céntimos o un importe no expresado en dólares, escribe en mayúscula la referencia al país o región de la moneda utilizada entre paréntesis inmediatamente después de la primera referencia. Las referencias de moneda posteriores se tratan siguiendo las directrices anteriores.

•         **Usar:**`99 cents (US currency)` para la primera referencia y `99 cents` para las referencias posteriores.
  

•         **Evitar:**`$0.99 (US currency)`, `$0.99 USD cents`, `USD$0.99 cents`.
  

Permisos

Un permiso es la capacidad de llevar a cabo una acción específica. Por ejemplo, borrar una incidencia constituye un permiso.

Un rol es un conjunto de permisos que se pueden asignar a un usuario. Hay distintos niveles de roles.

• Cuentas (por ejemplo, propietario de la organización, administrador de facturación para una cuenta empresarial)
• Recursos (por ejemplo, escribir para un repositorio, administrar un aviso de seguridad)
• Equipos (por ejemplo, mantenedor de equipo)

El acceso de una persona hace referencia generalmente a todas las capacidades que tiene la persona en un contexto determinado, independientemente de los roles o permisos individuales de los que proceden esas capacidades.

Usa solo permiso o rol cuando sea importante distinguir entre los dos. De lo contrario, usa acceso.

•         **Uso:** Para crear un rol de repositorio personalizado, se elige un rol heredado y luego se agregan permisos individuales.
  

•         **Uso:** Gestión del acceso de un equipo al repositorio de su organización
  

•         **Uso:** Si tu pertenencia al equipo te otorga un nivel de acceso diferente al de tu función como propietario de la organización...
  

•         **Uso:** Las personas con acceso de escritura pueden…
  

•         **Evite:** Los usuarios con acceso de escritura pueden…
  

•         **Evite:** Los usuarios con el rol de escritura pueden…
  

•         **Evite:** Los usuarios con permisos de escritura pueden…
  

•         **Evite:** Los usuarios con privilegios de escritura pueden…
  

Cuando especifiques el acceso necesario para realizar una acción, haz referencia únicamente al rol del mismo nivel que la acción. Por ejemplo, necesitarás acceso de administrador a un repositorio, que es un rol de nivel de repositorio, para configurar ramas protegidas. Puedes obtener acceso de administrador a un repositorio si eres propietario de la organización, un rol de nivel de organización, pero el rol de nivel de repositorio es lo que realmente rige la capacidad de realizar la acción, por lo que es el único rol que se debe mencionar.

•         **Use:** Los usuarios con acceso de escritura a un repositorio pueden hacer X en el repositorio.
  

•         **Evite:** Los propietarios de la organización y los usuarios con acceso de escritura pueden hacer X en el repositorio.
  

Para más información sobre la elección de palabras para las instrucciones de permisos, consulta Contenido de un artículo de Documentación de GitHub en el modelo de contenido.

Preposiciones

Evita terminar una frase con una preposición a menos que la frase reescrita suene extraña o demasiado formal.

Nombres de producto

Consulta la sección "Nombres de producto" de esta guía.

Términos para usar o evitar

elección de palabras

Verbos ambiguos

Cuando se requiera una tarea o se prefiera una opción a otra, evite utilizar verbos auxiliares modales ambiguos como "puede", "podría", " debe", "debería", "podría" y "haría". Estos verbos se pueden interpretar como un comando o una sugerencia. En su lugar, use verbos que indiquen claramente si la acción es necesaria o opcional. Si algo es una opción o sugerencia, puede usar estos verbos siempre y cuando deje claro que la acción es opcional.

•         **Uso:** puede decidir qué métodos abreviados de teclado usar.
  

•         **Uso**: Use este comando `git clone` para clonar un repositorio.
  

•         **Evitar:** puede usar el comando `git clone` para clonar un repositorio.
  

•         **Evite:** podría eliminar la rama.
  

Plurales invisibles

Evite plurales invisibles, que son palabras que tienen significado ambiguo porque se pueden interpretar como singulares o plurales. Por ejemplo, "recuperación de archivos" podría hacer referencia a la recuperación de un único archivo o varios archivos.

•         **Uso:** Después de recuperar el archivo, seleccione dónde guardarlo.
  

•         **Evitar:** Después de la recuperación de archivos, seleccione dónde guardarlo.
  

Nominalizaciones

Evite las nominalizaciones, que son nombres creados a partir de verbos o adjetivos. Las nominalizaciones pueden hacer que las oraciones sean más largas, más difíciles de entender y más difíciles de traducir.

•         **Uso:** una vez finalizado el flujo de trabajo, el paquete estará visible.
  

•         **Advertencia:** una vez que el flujo de trabajo haya llegado a su conclusión, el paquete estará visible.
  

Cadenas de sustantivos

Evita los modificadores apilados (cadenas de sustantivos), que pueden dar lugar a traducciones incorrectas porque es posible que las traducciones no sepan qué palabra modifica la otra. Puedes reformular la cadena de sustantivos utilizando una preposición. Si el uso de un modificador en cadena es esencial, asegúrate de que la información de contexto sea clara para que tanto los lectores como el traductor puedan entender lo que se está modificando. * Usar: Configuración de fuentes predeterminadas para repositorios públicos. * Evitar: Configuraciones de origen predeterminadas del repositorio público

Sustantivos y pronombres imprecisos

Si un pronombre parece referirse a más de un antecedente, vuelve a formular la frase para que el antecedente esté claro o reemplaza el pronombre por un sustantivo para eliminar la ambigüedad.

•         **Use:** Después de realizar la confirmación final en la rama y combinar la solicitud de incorporación de cambios, puede eliminar la rama.
  

•         **Evite:** Después de realizar la confirmación final en la rama y combinar la solicitud de incorporación de cambios, puede eliminarla.