Durante el último mes, he trabajado en una prueba de concepto para explorar una forma diferente de gestionar la documentación de BI para uno de nuestros clientes.

El problema es bien conocido: los paneles de control evolucionan, la lógica de negocio cambia, las fuentes de datos se actualizan y la documentación queda rápidamente desactualizada. Además, el conocimiento suele estar repartido entre Tableau, SQL, Confluence y los distintos miembros del equipo.

La prueba de concepto analiza si podemos lograr que la documentación evolucione en mayor medida en consonancia con los propios activos de BI, combinando el control de versiones, los agentes de IA y la revisión humana.

Creación de un flujo de trabajo de documentación autónomo

La idea principal no consistía simplemente en pedirle a un modelo de IA que examinara un panel de control y redactara la documentación.

En cambio, el flujo de trabajo divide las tareas en diferentes responsabilidades.

Un agente de documentación analiza el panel de control, sus fuentes de datos y la lógica relacionada, y elabora la primera versión de la documentación.

A continuación, un agente revisor evalúa ese resultado en cuanto a claridad, coherencia, exhaustividad y nivel adecuado de detalle.

Los resultados también se desglosan por público:

• Guía del usuario: cómo deben utilizar e interpretar el panel de control los usuarios de la empresa
• Documentación técnica: cómo funciona el panel de control y qué necesita un desarrollador de datos/BI para mantenerlo
• Conocimientos internos: detalles de implementación, conclusiones de investigaciones y contexto técnico que deben mantenerse en el ámbito interno.

La revisión humana sigue siendo el último punto de control antes de que se confirme o se publique cualquier cosa.

Proporcionar a los agentes un repositorio de BI con control de versiones

Para que este flujo de trabajo funcione de forma fiable, los agentes necesitan algo más que el propio panel de control.

Por lo tanto, el repositorio reúne los principales activos que sustentan el entorno de BI:

• SQL y lógica de negocio

• libretas de Tableau sincronizadas

• Fuentes de datos de Tableau publicadas

• documentación del panel de control

• herramientas para la sincronización, el seguimiento del origen y la publicación

Tableau Cloud sigue siendo la fuente de referencia para los paneles.

Git ofrece una representación controlada por versiones de los recursos que les rodean, lo que facilita la revisión de los cambios, la identificación de las dependencias y la comprensión de cómo ha evolucionado un panel de control a lo largo del tiempo.

De Tableau a Confluence

A grandes rasgos, el flujo objetivo es el siguiente: 

En primer lugar, el último libro de Tableau y sus fuentes de datos correspondientes se replican en Git. El repositorio también contiene la información SQL relacionada y los datos sobre dependencias, lo que proporciona a los agentes el contexto necesario para comprender cómo funciona el panel de control.

A partir de ahí, un agente encargado de la documentación examina el panel de control y elabora la primera versión de la Guía del usuario, la Documentación técnica y, cuando resulte útil, los Conocimientos internos. A continuación, un agente revisor comprueba los borradores para garantizar su claridad, coherencia y el nivel adecuado de detalle para cada público objetivo.

El resultado es revisado por una persona antes de que se realice cualquier confirmación o publicación. Una vez aprobados, la guía de usuario y la documentación técnica se publican desde Git en Confluence, mientras que los conocimientos de ingeniería más detallados permanecen dentro del repositorio.

Esto ya nos proporciona un proceso repetible para documentar un panel de control desde cero. El siguiente paso consiste en ampliar ese flujo de trabajo para realizar actualizaciones incrementales de la documentación cuando ya existe documentación previa.

En lugar de revisar o volver a generar toda la documentación cada vez que se produce un cambio, Git nos permite saber qué activos de BI han cambiado —por ejemplo, un libro de Tableau, una fuente de datos o una transformación SQL—, mientras que el linaje ayuda a identificar qué paneles documentados pueden verse afectados.

De este modo, el flujo de trabajo podría centrarse únicamente en esos paneles de control y evaluar si el cambio requiere realmente una actualización de la documentación. Un cambio en el diseño visual, por ejemplo, puede no tener ningún impacto, mientras que un cambio en el cálculo de un KPI podría requerir la actualización tanto de la documentación técnica como de la guía del usuario.

A esto me refiero cuando hablo de actualizaciones incrementales de la documentación: pasar de «documentar este panel de control» a «entender qué ha cambiado, decidir si la documentación se ve afectada y actualizar solo lo necesario».

Lo que he validado

Probé el PoC con paneles de control reales, lo que me ayudó a ajustar el flujo de trabajo en función de casos de uso reales.

Algunos de los aspectos principales que perfeccioné fueron:

• separar la documentación destinada a las empresas de la documentación técnica

• asegurarse de que la documentación refleje lo que los usuarios pueden hacer en el panel de control, y no solo su vista predeterminada

• mantener un registro detallado de los hallazgos técnicos para el equipo de BI sin añadir una complejidad innecesaria a la documentación destinada a los usuarios

• mantener la documentación original en Git y publicar únicamente el contenido relevante en Confluence

• incorporar una revisión manual antes de que la documentación se publique o se incorpore al sistema

Tras probar el enfoque con los usuarios, me dieron luz verde para seguir avanzando hacia su puesta en producción.

Por qué es importante esto y qué he aprendido

El valor de la prueba de concepto (PoC) no radica únicamente en el ahorro de tiempo en la documentación. Disponer de los activos de BI en Git nos proporciona un historial claro de los cambios, mientras que el flujo de trabajo automatizado reduce el esfuerzo manual necesario para comprender los paneles de control y mantener su documentación actualizada.

Una de las principales lecciones fue que no basta con proporcionar a un agente acceso a las herramientas adecuadas: la calidad del contexto es igual de importante.

Un libro de Tableau por sí solo solo muestra una parte del panorama. Para comprender correctamente un panel, el agente también puede necesitar su fuente de datos, el código SQL que hay detrás, la información sobre el linaje de los datos, la documentación existente y los conocimientos compartidos sobre el funcionamiento de la plataforma de BI. Mantener todo ese contexto reunido en un repositorio estructurado hace que el agente resulte más útil y reduce la cantidad de información que hay que proporcionar manualmente cada vez.

También he comprobado que separar las responsabilidades funciona mejor que pedirle a un solo agente que se encargue de todo. El redactor puede centrarse en comprender el panel de control, mientras que el revisor se centra en la claridad, la coherencia y en si el nivel de detalle es el adecuado para el público al que va dirigido.

Por último, la revisión humana sigue siendo importante. El objetivo no es eliminar a las personas del proceso, sino que dediquen sus esfuerzos no a recopilar información ni a redactar los primeros borradores, sino a aquellas áreas en las que el contexto empresarial y el criterio son más importantes.

Estas lecciones van más allá de Tableau. Los mismos principios se aplican a muchos casos de uso relacionados con la inteligencia empresarial (BI) y los datos: proporcionar a los agentes un contexto fiable, definir responsabilidades claras y mantener el control humano en aquellos puntos en los que la interpretación es fundamental.

‍

Próximos pasos

Mi siguiente paso es seguir probando el flujo de trabajo con paneles de control que tengan diferentes estructuras y niveles de complejidad.

Por ahora, quiero mantener el proceso bajo control: los agentes pueden investigar, redactar y revisar, pero la aprobación final sigue recayendo en las personas.

Una vez que la base de documentación sea lo suficientemente amplia, el siguiente reto consistirá en automatizar las actualizaciones incrementales de la documentación: detectar los cambios relevantes en los activos de BI, identificar qué documentación puede verse afectada y pedir a los agentes que revisen únicamente las partes pertinentes.