Contenido de un artículo de GitHub Docs

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.

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.
  • Uso: "Navegar por las acciones en el editor de flujo de trabajo"
  • Usa: “Ejemplo de configuración de un codespace”
  • Evita usar 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 26 caracteres.
  • Títulos de temas de mapa: 63 caracteres y shortTitle 29 caracteres.
  • Títulos de artículos: 80 caracteres, 60 si es posible, y shortTitle 30 caracteres, siendo 20-25 caracteres 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.
  • Uso: "Los 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

Cada página y artículo tiene una introducción que describe lo que se trata. El texto que usamos para las intros también se muestra dentro de los resultados de la búsqueda, lo que hace que sean importantes para SEO.

Cómo escribir una introducción

• Las introducciones deben ser concisas, idealmente de una oración.
• Las intros ayudan a las personas a saber si están en el lugar adecuado para lo que necesitan. Permite al usuario saber qué valor se les proporciona, usando palabras que usarían y buscarían.
• Las intros también son una invitación para continuar leyendo. Una buena introducción asegura al lector que su tiempo está bien invertido.
• Si un término importante tiene un acrónimo relacionado que se usa generalmente en su lugar, incluya el acrónimo en la introducción. (Ejemplo: Optimización del motor de búsqueda y SEO).
• Por último, revise la introducción para asegurarse de que es fácil de usar el motor de búsqueda, incluidas las palabras clave y frases pertinentes.

Declaraciones 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 declaración de permisos

• Cuando un único conjunto de permisos se aplica a todos los procedimientos de un artículo, utiliza los metadatos iniciales de permisos.
• 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:
  • Personas con [ROL DE CUENTA]
  • [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].

Consulta Guía de estilo para obtener más información sobre cómo dar formato a las instrucciones de permiso.

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 producto pueden contener enlaces a artículos que ayuden directamente a los usuarios a entender quiénes pueden usar la funcionalidad. Estos enlaces pueden ser enlaces en línea a los productos específicos o a los planes necesarios de GitHub.
• Ejemplos:
  • [Nombre de la característica] está disponible en [productos].
  • [Nombre de la característica] está disponible en repositorios públicos con [productos gratuitos] y en repositorios públicos y privados con [productos de pago].

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. * Administrar una regla de protección de rama

Conmutador de herramientas

Algunos artículos tienen contenido que varía en función de la herramienta que alguien use para completar una tarea, como el GitHub CLI o el 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, vea TDC 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

•         [AUTOTITLE](/enterprise-server@latest/admin/installation/installing-github-enterprise-server-on-aws)
  

•         [AUTOTITLE](/enterprise-server@latest/admin/configuration/enabling-subdomain-isolation)
  

Contenido de procedimientos

El contenido de procedimientos ayuda a los usuarios a realizar tareas. Para obtener más información, consulta Tipo de contenido instructivo 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 GitHub recursos.

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