Nuestro modelo de contenido explica la finalidad de cada tipo de contenido que creamos en GitHub Docs y qué debe incluirse cuando se escribe o actualiza un artículo. Usamos un modelo para garantizar que nuestro contenido comunique de forma coherente, clara y completa la información que los usuarios necesitan para lograr sus objetivos con GitHub.
Usamos estos tipos en toda la documentación para proporcionar una experiencia de usuario coherente. Cualquier tipo de contenido se aplica a cualquier producto o audiencia. Nuestros tipos de contenido evolucionan con el tiempo y agregamos nuevos tipos según es necesario. Solo publicamos contenido que sigue el modelo.
La coherencia ayuda a las personas a formar modelos mentales de la documentación y a comprender cómo buscar la información que necesitan a medida que vuelven a GitHub Docs a lo largo del tiempo. También es más eficiente mantener y actualizar contenido coherente, lo que facilita y agiliza la contribución a la documentación si es un colaborador de código abierto que realiza su primera confirmación o un escritor del personal de GitHub que documenta un producto totalmente nuevo.
Estructura del contenido
La documentación está organizada en varios niveles de jerarquía en nuestro sitio.
- Conjunto de documentos de nivel superior
- Categorías
- Temas relacionados
- Artículos
- Artículos
- Temas relacionados
- Artículos
- Categorías
Organizar los contenidos es un equilibrio entre hacer agrupaciones específicas que ayuden a la gente a encontrar lo que busca y limitar las capas de jerarquía por las que la gente debe navegar. Las jerarquías profundas con muchos temas de mapas anidados pueden dificultar la búsqueda de artículos concretos. Las jerarquías amplias con muchas categorías o artículos en el mismo nivel dificultan que las personas evalúen y decidan lo que quieren seleccionar.
Contenido de la página principal
La página principal de GitHub Docs, docs.github.com, resalta los temas más importantes que los usuarios quieren encontrar. Limitamos el número de conjuntos de documentos en la página principal para que los usuarios puedan encontrar la información y no se sature la página principal y dificulte las búsquedas.
La página principal incluye todos los conjuntos de documentos de nivel superior y algunas categorías. El contenido de la página principal está organizado en torno a los conceptos y prácticas de GitHub. Por ejemplo, el grupo "CI/CD and DevOps" incluye los conjuntos de documentos de nivel superior de GitHub Actions, GitHub Packages y GitHub Pages.
Adición de un conjunto de documentos a la página principal
El objetivo de la página principal es ayudar a los usuarios a encontrar información sobre el producto o la característica de GitHub sobre los que quieren obtener información. Cada elemento que se agrega a la página principal dificulta la detección de los demás elementos, por lo que limitamos el número de conjuntos de documentos en la página principal.
Si se crea un nuevo conjunto de documentos de nivel superior, se agrega a la página principal.
Si una categoría actúa como punto de partida para usar un producto o una característica de GitHub, se puede agregar a la página principal.
Por ejemplo, en el grupo "Security" de la página principal, además del conjunto de documentos de nivel superior Code security, se incluyen las categorías Supply chain security, Security advisories, Dependabot, Code scanning y Secret scanning, porque cada una de esas categorías es el punto de entrada para productos y características de GitHub. Security overview no se incluye en la página principal porque proporciona información adicional para usar productos de seguridad del código y no es una introducción a un producto o una característica.
Conjunto de documentos de nivel superior
Los conjuntos de documentos de nivel superior se organizan en torno a un producto, una característica o un flujo de trabajo principal de GitHub. Todos los conjuntos de documentos de nivel superior aparecen en la página principal de GitHub Docs. Solo tienes que crear un conjunto de documentos de nivel superior cuando haya una gran cantidad de contenido para incluirlo en el nuevo conjunto de documentos, varias categorías divididas en temas relacionados y el tema se aplique a productos, características o tipos de cuenta. Si el contenido podría caber en cualquier conjunto de documentos de nivel superior existente, probablemente pertenezca a ese conjunto de documentos.
- Los conjuntos de documentos de nivel superior tienen aproximadamente la misma importancia (cada uno se centra en un producto o una característica principal de GitHub.
- La mayoría de los conjuntos de documentos de nivel superior tienen un diseño de página de aterrizaje, a menos que haya una excepción importante. Por ejemplo, el conjunto de documentos Site policy no tiene guías ni artículos de procedimientos como otros conjuntos de documentos, por lo que no usa un diseño de página de aterrizaje.
- Los conjuntos de documentos de nivel superior pueden contener una combinación de categorías, temas de mapa o artículos.
Título de los conjuntos de documentos de nivel superior
- Basado en características o productos.
- Describe qué parte de GitHub está usando alguien.
- Ejemplos
Categoría
Las categorías se organizan en torno a una característica o un conjunto de tareas concreto dentro de un conjunto de documentos de nivel superior en consonancia con los temas del producto. El tema de una categoría es lo suficientemente específico como para que su contenido sea manejable y no aumente demasiado para usarlo. Algunas categorías aparecen en la página principal.
- Las categorías a menudo empiezan con un tamaño reducido y crecen con el producto.
- Las categorías pueden contener temas relacionados para subdividir el contenido en función de tareas o recorridos de usuario más específicos.
- Usa artículos de procedimientos largos para agrupar fragmentos de contenido relacionados y mantener los artículos optimizados dentro de la categoría.
- Cuando las categorías tengan más de diez artículos, considera la posibilidad de dividir el contenido en temas relacionados o categorías adicionales.
- Las categorías pueden contener una combinación de temas o artículos de mapa.
Título de las categorías
- Basado en una tarea (comienza con un gerundio).
- Describe la finalidad o el objetivo general de usar la característica o el producto.
- Suficientemente general como para abordar futuras mejoras del producto.
- Los títulos de categoría deben tener un máximo de 67 caracteres y un
shortTitlecon menos de 27 caracteres. - Ejemplos
Introducción de las categorías
Todas las categorías tienen una introducción. La introducción debe ser una oración larga y lo suficientemente general como para abordar futuros cambios en el producto. Si cambias la estructura de una categoría de forma considerable, comprueba si es necesario actualizar la introducción.
Temas relacionados
Los temas relacionados introducen una sección de una categoría. Agrupan artículos dentro de una categoría en torno a flujos de trabajo o temas más específicos que forman parte de la tarea más amplia de la categoría.
Los temas relacionados contienen al menos dos artículos. Cuando los temas relacionados tienen más de ocho artículos, puede ser útil considerar la posibilidad de dividir el contenido en temas relacionados más específicos.
Por lo general, evite tener un tema de mapa dentro de otro tema de mapa a menos que sea la mejor manera de satisfacer una necesidad específica del usuario.
Título de los temas relacionados
- Basado en una tarea (comienza con un gerundio).
- Describe una tarea más específica dentro del flujo de trabajo más amplio de la categoría en la que se encuentra.
- Suficientemente general como para abordar futuras incorporaciones al producto.
- Los títulos de temas relacionados deben tener un máximo de 63 caracteres y un
shortTitlecon menos de 30 caracteres. - Ejemplos
Introducción de los temas relacionados
Todos los temas relacionados tienen una introducción. La introducción debe ser una oración larga y lo suficientemente general como para abordar futuros cambios en el producto. Si agregas o quitas artículos en un tema relacionado, comprueba si es necesario actualizar la introducción.
Artículo
Un artículo es la unidad básica de contenido de GitHub Docs. Aunque usamos varios tipos de contenido, todos se publican como artículos. Cada tipo de contenido tiene una finalidad, un formato y una estructura propios, pero usamos elementos estándar en todos los artículos, como las introducciones, para garantizar que los artículos proporcionen una experiencia de usuario coherente.
Orden del contenido
Organizamos el contenido de forma predecible en categorías, temas relacionados y artículos. Desde la aplicabilidad más amplia hasta la información más específica o avanzada, siguiendo este orden:
- Contenido conceptual
- Contenido referencial
- Contenido de procedimientos para habilitar una característica o configuración
- Contenido de procedimientos sobre el uso de una característica
- Contenido de procedimientos para administrar una característica o configuración
- Contenido de procedimientos para deshabilitar una característica o configuración
- Contenido de procedimientos para acciones destructivas (por ejemplo, eliminación)
- Información para solución de problemas
Reutilización de contenido
Usamos cadenas reutilizables y variables para usar el mismo fragmento de contenido, como un paso de un procedimiento o un párrafo conceptual, en varios lugares. Por lo general, no se reutilizan secciones grandes de artículos sin un motivo específico. Cuando una sección entera de un artículo puede ser relevante en más de un artículo, echa un vistazo a la finalidad de ambos. ¿Existe la oportunidad de crear un único artículo más largo? Consulta los modelos de contenido para determinar el mejor lugar permanente para la información e incluye un vínculo a él desde el otro artículo.