¿La documentación de nuestro producto realmente ayuda o perjudica nuestra visibilidad en IA? ¿Cómo deberían estructurarse las docs?

Tu problema con JavaScript probablemente es la causa. Aquí está la realidad técnica:

Cómo difieren los rastreadores de IA de Googlebot:

Tu sitio de docs en React:

Si el contenido se carga vía JavaScript después de cargar la página, los rastreadores de IA ven:

<div id="root"></div>

En vez de tu documentación real.

Soluciones (de menor a mayor esfuerzo):

1. Pre-renderizado/SSR - Renderiza páginas del lado del servidor para que el HTML contenga el contenido
2. Generación de sitio estático - Construye las docs en archivos HTML estáticos
3. Enfoque híbrido - SSR para páginas críticas, cliente para elementos interactivos

Validación rápida:

1. Ver el código fuente de la página (no el inspector) en tus docs
2. Si ves contenido real = bien
3. Si ves divs vacíos = la IA no ve nada

Opciones de frameworks:

• Docusaurus (estático + SSR)
• GitBook (pre-renderizado)
• Mintlify (estático)
• VitePress (estático)

Todos generan HTML que los rastreadores de IA pueden leer.

Más allá del tema de JS, hablemos de optimización de estructura:

Estructura de documentación que adora la IA:

1. Jerarquía clara de encabezados

H1: Nombre de la función
  H2: ¿Qué es [Función]?
  H2: Cómo usar [Función]
    H3: Paso 1
    H3: Paso 2
  H2: Solución de problemas
  H2: Preguntas frecuentes

2. Contenido con la respuesta primero Cada sección debe comenzar con una respuesta directa, luego explicar:

Bien: “Para instalar el Producto X, ejecuta npm install productx. Este comando descarga el paquete desde npm y lo agrega a tus dependencias.”

Mal: “Cuando estés listo para comenzar a usar nuestro producto, querrás asegurarte de que todo esté configurado correctamente. Primero, hablemos de las dependencias…”

3. Secciones autocontenidas Cada sección H2 debe tener sentido extraída de forma independiente. La IA puede citar solo una sección.

4. Definiciones explícitas No asumas contexto:

• “Producto X es una herramienta de gestión de proyectos que…”
• “El límite de la API es 100 solicitudes por minuto”
• “SSO (Single Sign-On) permite a los usuarios…”

Marcado de esquema para documentación: esto suele pasarse por alto:

Esquemas esenciales para docs:

1. Esquema Article/TechArticle

{
  "@type": "TechArticle",
  "headline": "Cómo configurar SSO",
  "datePublished": "2026-01-01",
  "dateModified": "2026-01-05",
  "author": {
    "@type": "Organization",
    "name": "Your Company"
  }
}

2. Esquema FAQPage - Para secciones de solución de problemas/FAQ

{
  "@type": "FAQPage",
  "mainEntity": [{
    "@type": "Question",
    "name": "¿Cómo restablezco mi contraseña?",
    "acceptedAnswer": {
      "@type": "Answer",
      "text": "Ve a Configuración > Seguridad > Restablecer contraseña..."
    }
  }]
}

3. Esquema HowTo - Para guías paso a paso

{
  "@type": "HowTo",
  "name": "Cómo instalar Producto X",
  "step": [{
    "@type": "HowToStep",
    "text": "Abre la terminal y ejecuta npm install..."
  }]
}

Impacto en IA:

El esquema no garantiza citas por IA, pero:

• Ayuda a la IA a entender el tipo de contenido
• Facilita la extracción de información
• Señala información estructurada y confiable
• Mejora el ranking en Perplexity (~10% factor)

Consejo de implementación:

Comienza con el esquema FAQPage en tus temas más consultados. Es el más fácil de implementar y de mayor impacto.

Perspectiva SEO documental con consideraciones para IA:

Lo que cambiamos en nuestras docs:

Estructura de URL que funciona:

Bien: /docs/features/sso-configuration Mal: /docs/article/12345

Las URLs descriptivas ayudan a la IA a entender el contenido antes de leer.

Enlazado interno:

Haz muchas referencias cruzadas entre docs relacionadas:

• “Aprende más sobre [función relacionada]”
• “Ver también: Solución de problemas [tema]”
• “Prerrequisitos: [otra doc]”

Esto ayuda a la IA a entender relaciones temáticas y da confianza en tu autoridad.

Señales de frescura:

• Muestra fechas de “Última actualización” visiblemente
• Usa lastmod preciso en el sitemap
• Actualiza realmente el contenido (la IA detecta cambios sustantivos)

Este hilo ha sido increíblemente útil. Aquí está mi plan de acción:

Inmediato (Semana 1):

1. Validar problema de JS - Listo, confirmado que el view-source muestra divs vacíos
2. Investigar pre-renderizado - Considerando Prerender.io como solución rápida
3. Priorizar páginas clave - Identificar 50 docs de mayor tráfico para SSR

Corto plazo (Semana 2-4):

4. Implementar pre-renderizado - Lograr que el HTML sea visible para los rastreadores de IA
5. Agregar esquema FAQPage - Empezar por la sección de solución de problemas
6. Reestructurar docs clave - Respuestas primero, encabezados claros

Mediano plazo (Mes 2-3):

7. Evaluación de plataforma - ¿Deberíamos migrar a una plataforma de docs estática?
8. Implementación completa de esquemas - TechArticle, HowTo en todo el sitio
9. Auditoría de contenido - Asegurar secciones autocontenidas en todas las docs

Métricas de éxito:

• View-source mostrando contenido real
• Seguimiento de citas en IA vía Am I Cited
• Más páginas de docs en respuestas de IA
• URLs específicas de docs apareciendo en citas

La reflexión:

Nuestra documentación podría ser nuestro mayor activo de visibilidad en IA: es completa, precisa y autorizada. Pero nada de eso importa si la IA no puede leerla.

Para otros equipos de documentación:

Revisa tu view-source ahora mismo. Si está vacío, eres invisible para la IA sin importar lo bueno que sea tu contenido.

¡Gracias a todos!