Nuestro modelo de contenido explica el propósito de cada tipo de contenido que creamos en GitHub Docsy qué incluir al escribir o actualizar un artículo. Usamos un modelo de contenido para asegurarnos de que nuestro contenido se comunique de forma coherente, clara y completa la información que las personas 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 encontrar la información que necesitan a medida que vuelven a GitHub Docs lo largo del tiempo. También es más eficaz mantener y actualizar contenido coherente, lo que facilita y acelera la contribución a los documentos si es un colaborador de código abierto que realiza su primera confirmación o un escritor en el GitHub personal que documenta todo un nuevo producto.
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 los usuarios a encontrar lo que buscan y limitar las capas de jerarquía por las que los usuarios deben 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 los usuarios evalúen y decidan lo que quieren seleccionar.
Contenido de la página principal
La GitHub Docs página principal, docs.github.com, resalta los temas más importantes que las personas 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 se organiza en torno a GitHub conceptos y prácticas. Por ejemplo, el grupo "CI/CD y DevOps" incluye conjuntos de documentos de nivel superior para GitHub Actions, GitHub Packagesy GitHub Pages.
Adición de un conjunto de documentos a la página principal
El objetivo de la página principal es ayudar a las personas a encontrar información sobre la característica o el producto sobre los GitHub 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 GitHub producto o característica, se puede agregar a la página principal.
Conjunto de documentos de nivel superior
Los conjuntos de documentos de nivel superior se organizan en torno a un GitHub flujo de trabajo principal, característica o producto. Todos los conjuntos de documentos de nivel superior aparecen en la GitHub Docs página principal. 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 son de una importancia aproximadamente igual entre sí (cada uno se centra en un GitHub producto o una característica principal).
- 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 de Directiva de sitio 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 alguien está usando.
- Ejemplos
Category
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 de mapas 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 de mapas 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 para GitHub Docs– mientras 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.