Durant el mes passat, vaig treballar en una prova de concepte per explorar una manera diferent de mantenir la documentació de BI per a un dels nostres clients.

El problema és familiar: els quadres de comandament evolucionen, la lògica empresarial canvia, les fonts de dades s'actualitzen i la documentació queda ràpidament obsoleta. El coneixement també tendeix a distribuir-se entre Tableau, SQL, Confluence i els membres individuals de l'equip.

La PoC explora si podem fer que la documentació evolucioni més estretament amb els propis actius de BI combinant el control de versions, els agents d'IA i la revisió humana .

Creació d'un flux de treball de documentació agentiu

La idea clau no era simplement demanar a un model d'IA que inspeccionés un quadre de comandament i escrivís documentació.

En canvi, el flux de treball separa la feina en diferents responsabilitats.

Un agent documentador investiga el quadre de comandament, les seves fonts de dades i la lògica relacionada, i prepara la primera versió de la documentació.

Un agent revisor avalua el resultat per determinar-ne la claredat, la coherència, la integritat i el nivell de detall adequat.

La sortida també està separada per públic:

• Guia de l'usuari: com els usuaris empresarials han d'utilitzar i interpretar el tauler de control
• Documentació tècnica: com funciona el quadre de comandament i què necessita un desenvolupador de dades/BI per mantenir-lo
• Coneixement intern: detalls de la implementació, resultats de la investigació i context d'enginyeria que haurien de romandre interns.

L'aprovació humana continua sent el punt de control final abans que es comprometi o es publiqui res.

Donar als agents un repositori de BI versionat

Perquè aquest flux de treball funcioni de manera fiable, els agents necessiten més que el tauler de control en si.

Per tant, el repositori reuneix els principals actius que hi ha darrere de l'entorn de BI:

• SQL i lògica de negoci

• llibres de treball de Tableau duplicats

• fonts de dades publicades de Tableau

• documentació del tauler de control

• utilitats per a la sincronització, el llinatge i la publicació

Tableau Cloud continua sent la font de veritat per als quadres de comandament.

Git proporciona una representació controlada per versions dels recursos que els envolten, cosa que facilita la inspecció de canvis, la connexió de dependències i la comprensió de com ha evolucionat un quadre de comandament al llarg del temps.

De Tableau a Confluence

A un nivell alt, el flux objectiu és: 

Primer, el llibre de treball més recent de Tableau i les seves fonts de dades rellevants es reflecteixen a Git. El repositori també conté la informació relacionada amb SQL i dependències, cosa que dóna als agents el context que necessiten per entendre com funciona el tauler de control.

A partir d'aquí, un agent documental investiga el quadre de comandament i produeix la primera versió de la Guia de l'usuari, la Documentació tècnica i, si és útil, el Coneixement intern. A continuació, un agent revisor comprova els esborranys per garantir la claredat, la coherència i el nivell de detall adequat per a cada públic.

El resultat és revisat per una persona abans que es faci un commit o es publiqui res. Un cop aprovat, la Guia de l'usuari i la Documentació tècnica es publiquen des de Git a Confluence, mentre que el coneixement d'enginyeria més detallat roman intern al repositori.

Això ja ens proporciona un procés repetible per documentar un quadre de comandament des de zero. El següent pas és ampliar aquest flux de treball a actualitzacions incrementals de documentació quan ja existeix documentació.

En lloc de revisar o regenerar tota la documentació cada vegada que alguna cosa canvia, Git ens pot indicar quins actius de BI han canviat (per exemple, un llibre de treball de Tableau, una font de dades o una transformació SQL), mentre que el lineage ajuda a identificar quins quadres de comandament documentats poden estar afectats.

El flux de treball podria centrar-se només en aquests quadres de comandament i avaluar si el canvi realment requereix una actualització de la documentació. Un canvi de disseny visual, per exemple, pot no tenir cap impacte, mentre que un canvi en un càlcul d'indicadors clau de rendiment (KPI) podria requerir l'actualització tant de la documentació tècnica com de la guia de l'usuari.

Això és el que vull dir amb actualitzacions incrementals de documentació : passar de "documentar aquest quadre de comandament" a "entendre què ha canviat, decidir si la documentació s'ha vist afectada i actualitzar només allò que sigui necessari".

El que vaig validar

Vaig provar el PoC amb quadres de comandament reals, cosa que em va ajudar a ajustar el flux de treball en funció de casos d'ús reals.

Algunes de les principals coses que vaig refinar van ser:

• separar la documentació orientada a l'empresa de la tècnica

• assegurant-se que la documentació reflecteixi el que els usuaris poden fer al tauler de control, no només la vista predeterminada

• mantenir les conclusions tècniques detallades per a l'equip de BI sense afegir complexitat innecessària a la documentació orientada a l'usuari

• mantenint la documentació font a Git mentre publiquem només el contingut rellevant a Confluence

• afegir revisió humana abans que la documentació es compromi o es publiqui

Després de provar l'enfocament amb els usuaris, vaig obtenir el vistiplau per continuar movent-lo cap a la producció.

Per què això és important i què he après

El valor del PoC no rau només en l'estalvi de temps en la documentació. Tenir recursos de BI a Git ens proporciona un historial clar dels canvis, mentre que el flux de treball agentiu redueix l'esforç manual necessari per entendre els quadres de comandament i mantenir la seva documentació alineada.

Una de les principals lliçons va ser que donar a un agent accés a les eines adequades no és suficient: la qualitat del context importa igualment .

Un llibre de treball de Tableau per si sol només mostra una part de la imatge. Per entendre correctament un quadre de comandament, l'agent també pot necessitar la seva font de dades, l'SQL que hi ha darrere, informació de llinatge, documentació existent i coneixement compartit sobre com funciona la plataforma de BI. Mantenir aquest context junt en un repositori estructurat fa que l'agent sigui més útil i redueix la quantitat d'informació que s'ha de proporcionar manualment cada vegada.

També vaig trobar que separar responsabilitats funciona millor que demanar a un agent que ho faci tot . El documentador es pot centrar en entendre el quadre de comandament, mentre que el revisor se centra en la claredat, la coherència i si el nivell de detall és adequat per al públic objectiu.

Finalment, la revisió humana continua sent important . L'objectiu no és treure les persones del procés, sinó desplaçar el seu esforç lluny de la recopilació d'informació i la redacció dels primers esborranys, i cap a les àrees on el context i el criteri empresarial importen més.

Aquestes lliçons van més enllà de Tableau. Els mateixos principis s'apliquen a molts casos d'ús de dades i intel·ligència empresarial: donar als agents un context fiable, definir responsabilitats clares i mantenir el control humà en els punts on la interpretació importa.

‍

Passos següents

El meu següent pas és continuar provant el flux de treball amb quadres de comandament que tinguin diferents estructures i nivells de complexitat.

De moment, vull mantenir el procés controlat: els agents poden investigar, redactar i revisar, però l'aprovació final encara queda en mans de la gent.

Un cop la base de documentació sigui prou gran, el següent repte serà automatitzar les actualitzacions incrementals de la documentació : detectar canvis rellevants en els actius de BI, identificar quina documentació pot estar afectada i demanar als agents que revisin només les parts rellevants.