Saltar al contenido principal

Documentación como Código (Docs-as-code)

En Soportea creemos que el manual de usuario, las guías de ayuda y la documentación pre-venta de un producto deben tratarse con el mismo rigor que el software. Por ello, implementamos el paradigma Docs-as-code.

La documentación de cada tenant no se edita en un editor visual cerrado; vive en archivos Markdown versionados bajo Git y se actualiza de forma automatizada mediante procesos de despliegue continuo.

El Ciclo de Vida del Conocimiento​

El flujo por el cual un cambio documental redactado por tu equipo llega a ser utilizado por el bot de Inteligencia Artificial consta de los siguientes pasos:

graph TD
    A[Redacción en Markdown] -->|Git Commit| B(Repositorio Fuente)
    B -->|Pull Request| C{Validación & CI}
    C -->|Aprobado & Merge| D[Merge a Main]
    D -->|GitHub Action| E[Soportea Docs Sync]
    E -->|Deploy & Reindex| F[Vectores pgvector actualizados]
    F -->|Bot AI| G[Respuestas RAG precisas]

1. Creación o Refactor​

El equipo de producto, soporte o un agente de documentación edita archivos .md en la carpeta acordada (ej. help/ o sales-help/). Cada artículo lleva un bloque de metadatos (frontmatter) que indica el estado del artículo:

---
title: "Cómo realizar un Fichaje"
description: "Guía paso a paso para que los operarios registren su jornada laboral."
source_verified: true
last_reviewed: "2026-05-27"
---

2. Push & PR en el Origen​

Los cambios se commitean y se suben a tu repositorio. Se abre una Pull Request para que una persona (o un auditor técnico) revise que las instrucciones coinciden con el comportamiento real de la interfaz y que no se revelan secretos corporativos.

3. Sincronización Determinista​

Una vez mergeada la Pull Request en el repositorio cliente, una GitHub Action empaqueta el contenido de origen de forma determinista y abre un Pull Request automatizado hacia el repositorio de Soportea.

  • El destino en Soportea (docs-site/docs/<slug-cliente>) se limpia y se reemplaza íntegramente con el origen para garantizar que no queden archivos huérfanos.
  • El PR pasa validaciones automáticas de sintaxis Markdown y compilación estática.

4. Refresco de Conocimiento (Reindexación)​

Cuando el PR se mergea en la rama principal de Soportea, se ejecuta el workflow de despliegue que:

  1. Copia el nuevo snapshot al servidor seguro de Soportea.
  2. Llama al endpoint firmado de /internal/reindex.
  3. El bot de Soportea procesa cada archivo de tu corpus, los divide en fragmentos lógicos (chunks), genera sus vectores de representación semántica (embeddings) utilizando Voyage AI y los almacena de forma aislada en la tabla bot.documentation_embeddings de PostgreSQL.

Ventajas del Modelo​

  • Trazabilidad Absoluta: Sabes exactamente quién, cuándo y por qué modificó una instrucción de soporte consultando el historial de commits.
  • Cero Drift: Si una funcionalidad cambia en el código y el commit de código incluye la actualización de la documentación, el bot aprenderá la nueva regla en el mismo instante en que se despliega la versión de tu app.
  • Control Humano: Ninguna edición documental de soporte llega al bot de cara al público sin pasar por un proceso de revisión formal (Pull Request).