Contenido de un artículo de Documentación de GitHub

Cada artículo incluye algunos elementos estándar y puede incluir elementos condicionales u opcionales. También usamos un orden estándar para el contenido de un artículo.

En este artículo

Acerca de la estructura de un artículo

Dentro de un artículo, hay un orden estándar de las secciones de contenido. Cada artículo contiene elementos necesarios. Los artículos también contienen elementos condicionales y elementos opcionales esbozados en el diseño o la creación del contenido. Consulta las siguientes directrices para obtener más información.

Captura de pantalla del artículo con el título, la introducción, los permisos, la llamada de productos, la sección conceptual, la sección de procedimientos y la tabla de contenido etiquetados.

Títulos

Los títulos describen completamente de qué trata una página y lo que el usuario aprenderá al leerla.

Elegir un título puede resultar difícil. Usa estas directrices generales como ayuda para crear títulos claros, útiles y descriptivos. Las directrices para cada tipo de contenido de este artículo proporcionan reglas más específicas para los títulos.

Títulos para todos los tipos de contenido

  • Los títulos describen claramente de qué trata una página. Son descriptivos y específicos.
    • Usa: “Examen de acciones en el editor de flujo de trabajo”
    • Usa: “Ejemplo de configuración de un codespace”
    • Evita: “Uso de la barra lateral del editor de flujo de trabajo”
    • Evita: “Ejemplo”
  • Los títulos tienen límites estrictos de longitud para mantenerlos fáciles de entender (y más fáciles de representar en el sitio):
    • Títulos de categorías: 67 caracteres y shortTitle con menos de 26 caracteres.
    • Títulos de temas relacionados: 63 caracteres y shortTitle con menos de 29 caracteres.
    • Títulos de artículos: 80 caracteres, 60 si es posible y shortTitle con menos de 30 caracteres (20-25 caracteres es lo ideal).
  • En los títulos solo se usa una mayúscula inicial.
    • Usa: “Cambio de un mensaje de confirmación”
    • Evita: “Cambio de un Mensaje de Confirmación”
  • Los títulos son coherentes dentro de un mismo tipo de contenido. Consulta las directrices específicas para cada tipo de contenido.
  • Los títulos son lo suficientemente generales como para abordar los cambios que se realicen en el producto, reflejar todo el contenido del artículo o incluir contenido sobre varios productos.
    • Usa: "Planes de facturación de GitHub"
    • Evita: "Billing plans for user and organization accounts"
  • Los títulos usan terminología coherente.
    • Desarrolla y sigue patrones dentro de una categoría o en temas similares.
  • Los títulos usan terminología del propio producto.
  • Escribe el título y la introducción al mismo tiempo.
    • Usa la introducción para desarrollar las ideas presentadas en el título.
    • Consulta las directrices para las introducciones para obtener más información.
  • Si es difícil elegir un título, ten en cuenta el tipo de contenido. A veces los problemas para elegir un título indican que otro tipo de contenido sería más adecuado.
  • Piensa en cómo aparecerá el título en los resultados de las búsquedas para varios productos.
    • ¿Qué palabras específicas necesitamos incluir en el título o la introducción para que los usuarios no lo confundan con contenido sobre otro producto?
  • Piensa en cómo se verá el título en producción.

Introducción

Todas las páginas tienen una introducción al principio que proporciona contexto y establece expectativas, lo que permite a los lectores decidir rápidamente si la página es relevante para ellos o no. Las introducciones también se muestran en los resultados de las búsquedas para proporcionar información contextual y ayudar a los lectores a elegir un resultado.

Cómo escribir una introducción

  • Las introducciones de los artículos tienen una longitud de una o dos oraciones largas.
  • Las introducciones de los temas relacionados y las categorías tienen una oración.
  • Las introducciones de la referencia de API tienen una oración.
    • La introducción de la página de una API debe definir la característica de modo que el usuario sepa si la característica satisface sus necesidades sin leer todo el artículo.
  • Las introducciones contienen un resumen general del contenido de la página que desarrolla con más detalle la idea que expresa el título.
    • Usa sinónimos sencillos de las palabras del título de la página para ayudar a los lectores a comprender la finalidad del artículo de forma diferente. Evita repetir palabras del título siempre que sea posible.
  • Las introducciones son relativamente perennes y generales, por lo que pueden abordar cambios futuros en el contenido de la página sin necesidad de actualizarlas con frecuencia.
  • Con el fin de facilitar las búsquedas, incluye palabras clave sobre el tema de la página en la introducción.
  • Cuando un término de la introducción tiene un acrónimo que usarás en otra parte del artículo, indica el acrónimo.
  • Las introducciones generalmente no contienen permisos para las tareas que contiene el artículo.

Instrucciones de permisos

Cada procedimiento incluye una instrucción de permisos que explican el rol necesario para realizar la acción descrita en el procedimiento, lo que ayuda a los usuarios a saber si podrán realizar la tarea.

A veces es conveniente mencionar los permisos necesarios en el contenido conceptual, especialmente en artículos conceptuales independientes. Asegúrate de incluir también una instrucción de permisos en los procedimientos relacionados (o escribe un artículo más largo que combine todo el contenido).

Cómo escribir una instrucción de permisos

  • Cuando un único conjunto de permisos se aplica a todos los procedimientos de un artículo, usa el texto preliminar permissions.
  • Cuando un artículo contiene varios procedimientos que requieren permisos diferentes, incluye una instrucción de permisos en cada encabezado correspondiente, antes de cada procedimiento.
  • No incluyas permisos en la introducción de un artículo.
  • Hay diferentes niveles de roles. Haz referencia únicamente al rol del mismo nivel que la acción. Por ejemplo, necesitas acceso de administrador a un repositorio (rol de nivel de repositorio) para configurar ramas protegidas. Puedes obtener acceso de administrador a un repositorio si eres propietario de la organización (rol de nivel de organización), pero el rol de nivel de repositorio es lo que realmente rige tu capacidad de realizar la acción, de modo que es el único rol que debes mencionar en la instrucción de permisos.
  • Lenguaje que debe usarse en una instrucción de permisos:
    • [ROL DE CUENTA] can [ACCIÓN].
    • People with [ROL DE CARACTERÍSTICA] access for a [CARACTERÍSTICA] can [ACCIÓN].
    • EVITA: [ROL DE CUENTA] and people with [ROL DE CARACTERÍSTICA] access for a [CARACTERÍSTICA] can [ACCIÓN].

Ejemplos de instrucciones de permisos

Llamada de productos

Usa la llamada de productos cuando una característica solo esté disponible en productos específicos y esa disponibilidad no se pueda indicar solo con la versión. Por ejemplo, si una característica está disponible para GHEC y GHES, puedes indicar la versión del contenido sobre la característica solo para GHEC y GHES. Si hay una característica disponible para Pro, Team, GHEC y GHES (pero no Free), usa una llamada de producto para indicar esa disponibilidad.

Todas las llamadas de productos se almacenan como contenido reutilizable en gated-features y se agregan al texto preliminar YAML de los artículos pertinentes.

Cómo escribir una llamada de productos

  • Las llamadas de productos siguen un formato estricto. Identifican claramente la característica y en qué productos está disponible.
  • Las llamadas de productos también incluyen un vínculo a los "productos de GitHub" y, en ocasiones, a otro artículo relacionado.
  • Ejemplos:
    • [Nombre de la característica] is available in [Productos]. For more information, see "GitHub’s products.”
    • [Feature name] is available in public repositories with [free product(s)], and in public and private repositories with [paid products]. For more information, see "GitHub’s products.”

Ejemplos de artículos con llamadas de productos

Revisa los archivos de origen y gated-features para ver cómo está escrito el contenido original.

Conmutador de herramientas

Algunos artículos tienen contenido que varía en función de la herramienta que el usuario utilice para realizar una tarea, como GitHub CLI o GitHub Desktop. Para la mayor parte del contenido, la misma información conceptual o de procedimientos será precisa para varias herramientas. Sin embargo, si la única manera de hacer que la información sea clara y precisa es distinguir el contenido por herramienta, usa el conmutador de herramientas. No uses el conmutador de herramientas solo para mostrar ejemplos en diferentes lenguajes. Utiliza solo el conmutador de herramientas si las tareas o los conceptos cambian en función de la herramienta que se use. Para más información, consulta Creación de conmutadores de herramientas en artículos.

Tabla de contenido

Las tablas de contenido se generan automáticamente. Para obtener más información, consulta Minitablas de contenido generadas automáticamente.

Contenido conceptual

El contenido conceptual ayuda a los usuarios a comprender o aprender sobre un tema. Para obtener más información, consulta Tipo de contenido conceptual en el modelo de contenido.

Contenido referencial

El contenido referencial proporciona información estructurada relacionada con el uso activo de un producto o característica. Para obtener más información, consulta Tipo de contenido referencial en el modelo de contenido.

Requisitos previos

Los requisitos previos son información que los usuarios necesitan saber antes de continuar con un procedimiento, de modo que puedan preparar todo lo que necesitan antes de iniciar la tarea.

Cómo escribir requisitos previos

  • Escribe los requisitos previos inmediatamente antes de los pasos numerados de un procedimiento.
  • Puedes usar una lista, una oración o un párrafo para explicar los requisitos previos.
  • También puedes usar una sección de requisitos previos aparte cuando:
    • La información de los requisitos previos es muy importante y no debe pasarse por alto.
    • Hay más de un requisito previo.
  • Para repetir o resaltar información importante sobre la pérdida de datos o acciones destructivas, también puedes usar una llamada de advertencia o peligro para compartir un requisito previo.

Directrices para el título de los requisitos previos

  • Cuando uses una sección aparte, utiliza un encabezado denominado Prerequisites.

Ejemplos de artículos con secciones de requisitos previos

Contenido de procedimientos

El contenido de procedimientos ayuda a los usuarios a realizar tareas. Para obtener más información, consulta Tipo de contenido de procedimientos en el modelo de contenido.

Contenido de solución de problemas

El contenido de solución de problemas ayuda a los usuarios a evitar o resolver errores. Para obtener más información, consulta Tipo de contenido de solución de problemas en el modelo de contenido.

Pasos siguientes

Cuando un artículo describe un paso en un proceso mayor o tiene un siguiente paso lógico que la mayoría de las personas querrán hacer, incluya una sección de pasos siguientes. Puede vincular personas a artículos u otros recursos de GitHub.

Ejemplos de secciones de pasos siguientes

## Next steps

- You can monitor self-hosted runners and troubleshoot common issues. See "Monitoring and troubleshooting self hosted runners."

- GitHub recommends that you review security considerations for self-hosted runner machines. See "Security hardening for GitHub Actions."

En este ejemplo de Introducción a los ejecutores autohospedados para la empresa, la sección de pasos siguientes incluye vínculos a procedimientos que alguien tendrá que hacer después de empezar a usar la característica descrita en el artículo.

## Next steps

After your enterprise account is created, we recommend learning more about how enterprise accounts work and configuring settings and policies. Follow the "Get started with your enterprise account" learning path.

En este ejemplo de Crear una cuenta empresarial, el siguiente paso vincula a dónde la mayoría de las personas que acaban de crear una cuenta de empresa querrán ir a continuación.

Información adicional

Si hay artículos adicionales que ayudan a los usuarios a completar su tarea o a aprender a usar el tema descrito en el artículo actual, inclúyalos en una sección de lectura adicional. Solo se incluyen vínculos a artículos que aún no se han vinculado dentro del contenido del artículo.

Incluya solo vínculos que ayuden a las personas con la tarea o el tema a mano. Es mejor centrarse y proporcionar a las personas recursos valiosos que ofrecerles todos los vínculos posibles.

Formatear las secciones de información adicional mediante listas sin ordenar. Consulta Guía de estilo para obtener información sobre cómo escribir vínculos.

Título y formato de las secciones de lecturas adicionales

## Further reading
- "[Article title](article-URL)"
- [External resource title](external-resource-URL) in External Resource Name