content-site-design

Diseño de sitios de contenido

Un sitio de contenido existe para que un lector pueda encontrar una página, confirmar que es la correcta, obtener la respuesta o comprensión que buscaba y pasar a lo siguiente. La mayoría de los lectores llegan desde la búsqueda a una página profunda, escanean antes de leer y se van una vez que tienen lo que necesitan. La forma más común en que los modelos se equivocan es diseñar la cáscara (héroe, tarjetas, barra lateral, alternador de modo oscuro) y descuidar la estructura propia del contenido: títulos vagos, encabezados que no dicen nada ("Resumen", "Introducción"), la respuesta tres párrafos abajo, una página que mezcla tutorial, referencia y opinión, texto de enlace como "aquí", sin fechas, y una búsqueda en el sitio que no devuelve nada útil.

Aplica los principios jerarquizados de interface-guidelines (todos pueden usarlo > dice la verdad > dice lo que significa > la respuesta va primero > los errores son recuperables > se mantiene firme > lo posible es visible > convención > pulido). Si esa habilidad está instalada, lee primero su SKILL.md. El tamaño del cuerpo tipográfico, la longitud de línea, el contraste y el reflujo se tratan allí (references/human-interface.md secciones 6 y 7); esta habilidad cubre la estructura del contenido, la navegación, la búsqueda y el lector agente.

Resumen

• Tipo de sitio: documentación, centro de ayuda, base de conocimiento, editorial o blog, o una combinación. Los sitios mixtos nombran un trabajo principal por sección.
• Lectores y su llegada: desde la búsqueda a una página profunda, desde dentro de un producto (enlace "?"), navegando o suscritos. ¿Quién es nuevo y quién es experto?
• Tareas principales: las 10 a 20 preguntas que los lectores traen, en sus propias palabras. Tómalas de los registros de búsqueda, tickets de soporte y publicaciones en foros, no del organigrama.
• Tipos de contenido: para documentación, cuáles de tutorial, cómo se hace, referencia, explicación; para editorial, cuáles de noticia, análisis, opinión, guía.
• Actualización: con qué frecuencia cambia el contenido, quién es el propietario de cada página, qué sucede cuando cambia una versión del producto.
• Lectores agentes: agentes de codificación que leen documentación, motores de búsqueda y respuesta que citan páginas, agentes de navegador que navegan. ¿Qué deben hacer bien?
• Quién escribe: solo el personal, o también usuarios (comentarios, respuestas de la comunidad)? Marca el contenido escrito por externos.

Reglas

Etiquetas: [E] empírico, [S] estándar o institucional, [P] profesional, [J] juicio. Las fuentes están en los archivos de referencia.

Páginas

• La respuesta primero. Los primeros dos párrafos llevan el punto principal; los detalles siguen en importancia descendente (pirámide invertida) [S: GOV.UK; P: NN/g]. Los lectores leen una fracción de las palabras de una página; una estimación que Nielsen situó en aproximadamente 20 a 28 % [P: Nielsen 2008, a partir de datos de Weinreich et al. 2008].
• Una página, un trabajo. Un tutorial enseña, una guía práctica dirige, la referencia describe, la explicación discute; no los mezcles en una página [P: Procida, Diátaxis].
• Los títulos son únicos, específicos y con las palabras clave al inicio, en las palabras del lector, de aproximadamente 65 caracteres o menos para que los resultados de búsqueda no los corten [S: GOV.UK]. Las páginas de tareas comienzan con un verbo ("Rotar una clave de API"); la orientación sobre una tarea usa la forma -ando/-endo ("Rotando claves de API") [S: GOV.UK].
• Un resumen debajo del título de una oración, 160 caracteres o menos, que agregue palabras que el título no tenga; el mismo texto sirve como meta descripción [S: GOV.UK].
• Los encabezados dicen lo que dice la sección, con las palabras clave al inicio, no "Resumen" o "Más información", y no formulados como preguntas; el contenido aún tiene sentido con los encabezados eliminados [S: GOV.UK]. Los niveles de encabezado siguen la estructura: un h1, sin niveles saltados [S: WCAG 1.3.1, 2.4.6].
• Oraciones y párrafos cortos, palabras sencillas. Divide oraciones de más de 25 palabras, mantén los párrafos en cinco oraciones o menos, explica un término especializado en su primer uso [S: GOV.UK]. Dirígete al lector como "tú", voz activa, condición antes de instrucción ("Para eliminar un proyecto, abre Configuración") [S: Guía de estilo para desarrolladores de Google].
• Listas numeradas para pasos, viñetas para conjuntos, tablas para comparaciones [S: Guía de estilo para desarrolladores de Google; GOV.UK].
• Formato para el escaneo: encabezados significativos y párrafos con la información principal al inicio contrarrestan el escaneo en forma de F, donde los lectores se saltan el lado derecho y las partes inferiores de una página [P: Pernice, NN/g 2017].
• Fechas que significan algo: "Última actualización: 4 nov 2026" con una breve nota de cambio para cambios sustanciales, y una fecha de publicación en los artículos. Las páginas antiguas que siguen siendo precisas dicen "Revisado" [S: Notas de cambio de GOV.UK; J].
• Notas al pie: GOV.UK las prohíbe para contenido de servicio; el contenido académico y editorial extenso puede necesitarlas. Decide según si los lectores deben verificar las fuentes [S: GOV.UK; J].

Enlaces

• El texto del enlace nombra el destino, con las palabras clave al inicio y único por destino en la página; nunca "haz clic aquí", "leer más" o "aquí" [S: GOV.UK, WCAG 2.4.4].
• Indica cuándo un enlace sale del sitio, abre un archivo o cambia de idioma: "Hoja de precios (PDF, 240 KB)" [S: GOV.UK].
• Enlaces donde ayudan, no apilados al final en "Lectura adicional"; los siguientes pasos al final de una página de tarea están bien cuando son específicos [S: GOV.UK].
• Cada encabezado tiene un ancla estable (#rotar-una-clave), con un control visible para copiar el enlace. Renombrar un encabezado mantiene el ancla anterior funcionando [J].
• Las URL son legibles y permanentes. Cuando una página se mueve, redirige la URL anterior; nunca permitas que los enlaces de documentación den 404 [J].

Navegación

• Los lectores aterrizan en páginas profundas. Cada página muestra dónde está (migas de pan o sección resaltada) y qué hay después y cerca [S: WCAG 2.4.8; P: Migas de pan de NN/g].
• Las etiquetas de navegación usan las palabras de los lectores y predicen su contenido (olor a información) [E: Pirolli y Card 1999].
• Al menos dos formas de llegar a una página: navegación más búsqueda, o un mapa del sitio [S: WCAG 2.4.5].
• Una lista de contenido en la página para páginas largas, generada a partir de h2 y h3, resaltando la sección actual [J].
• Paginación o "Cargar más" en lugar de desplazamiento infinito para archivos y resultados de búsqueda, para que los lectores puedan llegar al pie de página, volver a un lugar y compartir una posición [P: Desplazamiento infinito de NN/g].
• Documentación: una barra lateral organizada por tarea del lector y tipo Diátaxis, un selector de versión visible donde las versiones difieren, y un banner en páginas para versiones antiguas que enlace a la página actual [P: Procida; J].

Búsqueda

• La búsqueda es una ruta principal, no un complemento. El cuadro es visible en cada página, no oculto detrás de un ícono en escritorio [P: NN/g; J].
• Los resultados muestran el título de la página, su sección o tipo, un fragmento con las palabras coincidentes y la fecha. Tolera errores tipográficos y sinónimos de consultas reales [J].
• Las páginas sin resultados sugieren correcciones ortográficas, términos más amplios y páginas principales, y registran la consulta [J].
• Revisa las consultas sin resultados y las principales mensualmente; cada una nombra una página faltante, un sinónimo faltante o un mal título [P: Práctica común en documentación; J].

Comodidad de lectura

• El tipo de cuerpo, la medida, la altura de línea, el contraste y el reflujo siguen los fundamentos. En teléfonos, los lectores comprenden texto corto y simple tan bien como en escritorio, pero se ralentizan con texto difícil, por lo que el contenido difícil necesita estructura adicional en móvil [P: Moran, NN/g 2016].
• Sin intersticiales ni elementos fijos que cubran el texto; los anuncios y las solicitudes de suscripción al boletín nunca interrumpen la primera pantalla de la respuesta [S: WCAG 2.4.11 para enfoque; J].
• Las imágenes que transmiten información tienen texto alternativo que indica la información; las imágenes decorativas tienen texto alternativo vacío [S: WCAG 1.1.1]. Los diagramas tienen una explicación textual cercana [J].
• Los ejemplos de código son texto, nunca imágenes, con un control de copia y el idioma etiquetado. Las pestañas para variantes de idioma mantienen todas las variantes en el DOM [J].
• Los modos de impresión y lector producen el contenido sin el marco de navegación [J].

Para agentes

• El contenido está en el HTML, renderizado en el servidor, no ensamblado por JavaScript del cliente después de la carga, para que los rastreadores y agentes que no ejecutan scripts lo obtengan [J].
• La estructura semántica es la interfaz: encabezados, listas, tablas, code y pre con clases de idioma, figure y figcaption [S: WCAG 1.3.1].
• URL y anclas estables y citables, una URL canónica por página y una fecha en la página [J].
• Una copia limpia en Markdown de cada página de documentación en la misma URL con .md añadido, enlazada con rel="alternate" type="text/markdown", es una forma económica de dar a los agentes de codificación el contenido sin el marco. llms.txt en la raíz del sitio o la documentación es una propuesta de la comunidad; se ha medido una demanda baja para sitios generales, pero encaja en la documentación leída por agentes de codificación [P: Howard, llms.txt; sección 6 de foundation agent-surfaces].
• Sin instrucciones ocultas para agentes en el texto de la página, comentarios o elementos invisibles. Son indistinguibles de la inyección de indicaciones [J; sección 5 de foundation oversight].
• El contenido generado por el usuario (comentarios, respuestas de la comunidad, publicaciones en foros) está marcado como tal en el marcado y visualmente, con autor y fecha, para que agentes y personas puedan evaluarlo [J].

Orden de construcción

1. Tareas principales e inventario de contenido: cada página existente o planificada con su tipo, propietario, última revisión y la tarea que cumple. Elimina o fusiona páginas que no cumplen ninguna tarea.
2. Arquitectura de la información: secciones basadas en tareas de lectores y tipos de contenido; etiqueta con las palabras de los lectores; prueba las etiquetas con una prueba de árbol (las personas encuentran cinco tareas en un árbol solo de texto) [P: Prueba de árbol de NN/g].
3. Plantillas de página por tipo de contenido: título, resumen, fechas, cuerpo, pasos siguientes. Para documentación: plantillas de tutorial, cómo se hace, referencia, explicación (references/docs.md).
4. Escribe o reescribe primero las páginas de tareas principales con references/writing.md; una página completa y buena vale más que veinte esbozos.
5. Estructura HTML semántica: puntos de referencia, enlace de salto, migas de pan, barra lateral como nav con aria-current, contenido en la página, pie de página. Renderizado en el servidor.
6. Búsqueda con consultas reales de registros o la lista de tareas principales; ajusta los sinónimos.
7. Capa para agentes: URL canónicas, anclas, copias en Markdown, mapa del sitio, llms.txt opcional.
8. Estilo para lectura larga; la marca posee la apariencia (brand-identity).
9. Verificar (a continuación).

Verificar

1. Auditoría renderizada en una página de inicio, un artículo largo o página de referencia, una página de resultados de búsqueda y un 404:

   node <interface-guidelines>/scripts/audit.mjs <dist-o-url> --out audit-output
   

2. Prueba de tareas principales: para cada tarea principal, comienza desde una consulta de motor de búsqueda o la página de inicio y llega a la respuesta. Cuenta los pasos y observa dónde falló el olor a información. Hazlo una vez como persona con teclado en ancho de teléfono, y una vez como agente con solo la instantánea de accesibilidad.

3. Linter de contenido en cada página (la sección 8 de references/writing.md tiene un esquema de script): un h1; sin niveles de encabezado saltados; títulos únicos y de 65 caracteres o menos; resumen presente y de 160 o menos; sin encabezados o textos de enlace genéricos ("Resumen", "haz clic aquí", "leer más"); oraciones de más de 25 palabras marcadas; imágenes sin texto alternativo; fecha de última actualización presente.

4. Enlaces: rastrea en busca de enlaces internos rotos y anclas faltantes; verifica que las URL antiguas redirijan.

5. Verificación sin JS: obtén una página con curl y confirma que el contenido principal y los encabezados están en el HTML.

6. Búsqueda: ejecuta las 20 consultas principales y 5 errores tipográficos; la página correcta está entre las tres primeras.

7. Lectura por agente: dale a un agente solo la URL de una página de documentación o su copia en .md y pídele que realice la tarea; verifica que sigue la versión actual y cita el ancla de sección correcta.

Trampas

• Cuadrículas de tarjetas con avances de artículos como página de inicio de la documentación, sin puntos de entrada de tareas ni búsqueda.
• Encabezados llamados "Introducción", "Resumen", "Detalles" o escritos como preguntas.
• Páginas de preguntas frecuentes que recopilan preguntas no relacionadas en lugar de responderlas en las páginas donde surgen.
• La respuesta debajo de un largo preámbulo sobre por qué el tema es importante.
• Un tutorial que se convierte en referencia a mitad de camino, o una referencia rellena de opiniones.
• Artículos sin fecha, y "última actualización" establecida en la fecha de compilación en cada página.
• Contenido renderizado solo por JavaScript del cliente, pestañas cuyos paneles ocultos no están en el DOM, código como capturas de pantalla.
• Desplazamiento infinito en archivos y resultados de búsqueda.
• Texto de instrucciones para rastreadores de IA oculto en la página.
• Rediseñar un sitio de documentación mientras los títulos, encabezados y la búsqueda siguen rotos.

Referencias

Archivo	Leer cuando
references/writing.md	Escribir o editar páginas: títulos, resúmenes, encabezados, oraciones, enlaces, fechas, números, detalles editoriales y un esquema de linter
references/docs.md	Documentación y centros de ayuda: tipos Diátaxis con plantillas, páginas de referencia de API, ejemplos de código, versiones, registros de cambios, documentación para agentes de codificación
references/navigation-search.md	Estructura del sitio, etiquetas, barras laterales, migas de pan, listas de contenido, archivos, resultados de búsqueda, 404