1El problema
En las empresas de tecnología, dos tipos de contenido viven separados: la documentación técnica (lo que el producto hace de verdad) y los artículos del centro de ayuda (lo que lee el usuario final). Cuando el producto cambia, alguien tiene que acordarse de actualizar la documentación — y luego acordarse de qué artículos afectó ese cambio, y reescribir cada uno a mano. Ese ciclo se rompe todo el tiempo: la doc avanza y los artículos se quedan desactualizados en silencio.
Queríamos cerrar ese ciclo con IA, pero sin sacar al humano de la decisión. La idea: la doc técnica es la única fuente de la verdad y vive dentro de la propia app. Cuando se sube una nueva versión de un doc, el sistema descubre qué artículos fueron impactados y redacta las revisiones — pero nada se publica sin que una persona lo apruebe. La IA hace el trabajo pesado; el humano conserva la última palabra.
2El stack
"Stack" es la palabra para el conjunto de piezas de software que sostienen un producto. La decisión guía de BaseViva fue apoyarse en un stack de nube gestionado y dejar que él maneje la plomería, para que el esfuerzo fuera a la IA y a la detección de impacto. El front es una app web en React (construida con Vite); el backend es AWS Amplify Gen 2 — un kit que conecta login, base de datos y API desde código TypeScript. Mira el término para la versión en lenguaje sencillo.
El login corre sobre Amazon Cognito, y toda la API es una capa (AppSync) generada automáticamente a partir de los modelos de datos — no hay CRUD escrito a mano ni un gateway de API aparte. Los datos viven en , y cada modelo está aislado : cada usuario solo ve sus propios datos. La IA generativa corre sobre , alcanzada a través de unas pocas funciones pequeñas.
La app React en el navegador. Dos cosas corren aquí mismo en el cliente: partir el markdown en secciones (chunking) y la detección de impacto, calculada sobre vectores cargados del servidor.
Login por email a través de Amazon Cognito. El token que emite lleva la identidad que marca cada registro como propiedad de ese usuario.
Toda la API es una capa que Amplify genera a partir de los modelos de datos — sin CRUD a mano, sin gateway de API aparte.
Diez modelos en , cada uno aislado . Entre ellos, el modelo Embedding guarda un ítem por vector de sección.
Cuatro pequeñas funciones — embed, rewrite, outline y draftArticle — existen por una sola razón: llamar a la IA. Cada una con el permiso mínimo para el modelo que usa.
corre dos modelos: Titan v2 para convertir texto en vectores (embeddings) y Claude para escribir los borradores de artículos.
Una nota deliberada sobre dónde corre la lógica: la IA (en Bedrock) y el almacenamiento (en DynamoDB) viven en el servidor, pero el chunking del markdown y la detección de impacto son funciones puras que corren en el navegador, sobre vectores cargados bajo demanda. Esa división importa para la próxima sección.
3Cómo usamos la IA
La IA aparece en dos momentos. El primero es cuando subes un doc por primera vez: todavía no hay artículos, así que la IA propone los iniciales. El segundo — el corazón del producto — es cuando subes una nueva versión de un doc que ya tiene artículos: el sistema detecta qué cambió, encuentra los artículos impactados y redacta las revisiones. Toca cada paso para seguir ese segundo flujo.
Subes una nueva versión de un doc técnico (Markdown o .docx). La app extrae el texto y guarda el archivo original; cada subida se vuelve una nueva versión, sin sobrescribir la anterior.
El markdown se parte en secciones por sus encabezados, y el sistema compara la versión vieja con la nueva sección por sección para ver exactamente qué secciones cambiaron. Esto ocurre sobre por sección, no sobre el documento entero.
Cada artículo recuerda de qué sección del doc vino (su ). Así, los artículos impactados son simplemente los vinculados a una sección que cambió — una señal confiable, en vez de un frágil puntaje de similitud artículo-vs-doc.
Para cada artículo impactado, la IA (Claude, en Bedrock) escribe una revisión como borrador — una . Nunca sobrescribe el artículo publicado; produce una versión propuesta más un resumen corto de lo que cambió.
Una persona revisa la propuesta junto a un diff contra la versión publicada, y decide: aprobar, editar y aprobar, o rechazar. Solo al aprobar se crea una nueva versión publicada del artículo. Nada se publica por sí solo.
En la primera subida de un doc, el flujo es un poco distinto: todavía no hay artículos, así que eliges cómo generarlos — todo el doc como un artículo, o varios artículos divididos por sus encabezados. En cualquier caso, cada borrador entra como una propuesta de tipo "artículo nuevo", y la misma revisión humana decide si se vuelve un artículo publicado.
4Decisiones clave
Mantener un humano en el ciclo, siempre. Habría sido más simple dejar que la IA publicara sus revisiones automáticamente. Elegimos lo contrario: la IA solo produce un borrador, y nada llega al usuario final sin que una persona lo apruebe. Un centro de ayuda es una promesa al cliente — equivocarse a escala es peor que actualizarlo un poco más lento.
El doc técnico es la única fuente de la verdad, dentro de la app. En vez de depender de Git o de servicios externos, la fuente de la verdad es el archivo que subes — y el disparador de todo es simplemente subir una nueva versión. Sin integración que configurar, sin pipeline que vigilar. Sube un doc, y el ciclo empieza.
Upload en vez de GitHub. La premisa original era distinta: los docs vivirían en un repositorio de GitHub, y un push ahí dispararía la actualización. Lo descartamos a propósito — una integración con Git trae auth, webhooks y todo un paso de configuración antes de que alguien obtenga valor. Como esto se construyó en vivo en un curso, elegimos el camino que llega al punto más rápido: la persona sube el doc técnico directo a la plataforma, y la IA genera los artículos a partir de él. El modelo sigue tratando la subida como "una nueva versión", así que volver a conectar Git después es una adición, no una reescritura.
Nunca sobrescribir — siempre versionar. Tanto los docs técnicos como los artículos están versionados: una nueva subida o una nueva revisión aprobada crea una nueva versión, la anterior se queda. Eso es lo que permite mostrar un diff, mantener un registro de auditoría, y dejar que un humano compare el artículo publicado con el cambio propuesto lado a lado.
Trabajar por sección, no por documento entero. Los docs técnicos reales son grandes. Tratar un doc como un solo bloque se rompe de varias formas, así que hicimos de la la unidad de trabajo — para dividir en artículos, para embeddings y para detección de impacto. Esta sola decisión es la que hace que el resto funcione; la próxima sección explica por qué.
5Siendo más técnico…
Esta sección es para quien quiera mirar bajo el capó. Nada de esto es necesario para entender el producto — pero estas decisiones son las que hicieron que la detección de impacto fuera confiable en vez de frágil.
Detección de impacto anclada en la sección, no en similitud artículo-vs-doc. Nuestro primer instinto fue comparar cada artículo de ayuda contra cada sección del doc por . La medición real mató esa idea: un artículo amigable y una sección técnica seca puntúan bajo aun cuando tratan de lo mismo, así que cualquier umbral en esa escala es frágil — causó un bug de "no se propone nada". La señal confiable es otra: comparar doc v1 contra doc v2, sección por sección (mismo tipo de texto), separa con nitidez. Así el disparador real pasó a ser: cada artículo registra el encabezado del que vino; cuando esa sección cambia entre versiones, el artículo está impactado — directo, sin el puntaje frágil.
Un embedding por sección, guardado de a una fila. Un embedding del documento entero es truncado por el límite de entrada del modelo y diluye un cambio localizado en un solo vector — dos versiones hasta pueden verse idénticas porque ambas truncan en el mismo comienzo. Así que generamos un embedding por sección. Cada (unos 1024 números, ~21 KB) se guarda como una fila en la base de datos, indexada por la versión a la que pertenece. Un intento anterior guardaba todo esto en el almacenamiento local del navegador y reventaba su cuota de ~5 MB con docs grandes; moverlo al servidor lo resolvió de forma definitiva.
Partir el markdown programáticamente, usar la IA solo para los títulos. Pedirle a la IA un JSON con el texto de cada sección revienta el límite de tokens de salida — el JSON vuelve truncado, el parse falla, y cae al fallback de "un artículo". Así que la división por encabezados se hace de forma determinista en el código, y la IA se usa solo para mejorar los títulos de los artículos, nunca para devolver el contenido. Un pequeño cambio de responsabilidad que, en silencio, eliminó toda una clase de fallas.
Permisos de mínimo privilegio por función de IA. Cada solo puede llamar al modelo exacto que necesita: la función de embedding alcanza solo Titan; las de escritura alcanzan solo Claude. Ningún secreto vive en el repositorio — las funciones hablan con la IA a través de su rol de ejecución, nunca por una clave en el código.
6Lo que aprendimos
Mide antes de confiar en una métrica. Asumimos que la similitud semántica entre un artículo y un doc sería una buena señal de impacto. No lo era — y solo la medición real lo mostró. La lección con la IA es validar la señal contra números reales antes de construir toda una función encima.
La granularidad decide todo. Trabajar a nivel de documento falló en tres frentes a la vez — embeddings truncados, JSON roto, progreso invisible. Bajar al nivel de sección arregló los tres. Con la IA, el tamaño de la unidad que procesas suele importar más que el prompt mismo.
Las operaciones largas de IA necesitan progreso visible. Generar N artículos o embeber N secciones toma tiempo, y un único spinner global se siente como una pantalla congelada. Dividir el trabajo pesado en pasos pequeños y mostrar "ítem X de N" convierte la espera en algo que se siente en construcción — la misma lección que llevamos a través de cada producto.
7Qué significa esto para tu empresa
La idea de BaseViva — mantener una única fuente de verdad, detectar qué impacta cada cambio y dejar que la IA redacte la revisión, siempre con un humano aprobando — no es exclusiva de los centros de ayuda. Es un patrón que puedes tomar prestado: cerrar la brecha entre una fuente que cambia y el contenido que depende de ella, sin sacar a la persona de la decisión. Así se traslada a otros contextos.
Cuando cambia una política, una plantilla de contrato o una spec de producto, el sistema marca cada documento derivado — FAQs, playbooks, material de capacitación — que el cambio toca, y redacta la actualización para que un revisor la apruebe. Se acabaron los manuales desactualizados que nadie notó.
Mantén la wiki del equipo honesta: cuando el código o el runbook cambian, los docs de onboarding y las guías internas que lo referencian se marcan y se redacta una revisión — para que el conocimiento que lee un nuevo miembro coincida con lo que el equipo de verdad hace hoy.
Cuando un curso, una herramienta o una referencia cambia, las lecciones, guiones y material de apoyo que dependen de ello se marcan para revisión — para que un cuerpo de contenido educativo se mantenga al día sin revisar cada archivo a mano.
La conclusión: donde sea que el contenido derive de una fuente que sigue cambiando, detectar el impacto y redactar la revisión — con un humano aprobando — supera a acordarse de actualizar todo a mano. Esa es la pieza que vale adaptar a tu contexto.