Over the past month, I worked on a proof of concept to explore a different way of maintaining BI documentation for one of our clients.

The problem is familiar: dashboards evolve, business logic changes, datasources are updated, and documentation quickly becomes outdated. Knowledge also tends to be distributed across Tableau, SQL, Confluence and individual team members.

The PoC explores whether we can make documentation evolve more closely with the BI assets themselves by combining version control, AI agents and human review.

Building an agentic documentation workflow

The key idea was not simply to ask an AI model to inspect a dashboard and write documentation.

Instead, the workflow separates the work into different responsibilities.

A documenter agent investigates the dashboard, its datasources and related logic, and prepares the first version of the documentation.

A reviewer agent then evaluates that result for clarity, consistency, completeness and the appropriate level of detail.

The output is also separated by audience:

• User Guide — how business users should use and interpret the dashboard
• Technical Documentation — how the dashboard works and what a Data/BI developer needs to maintain it
• Internal Knowledge — implementation details, investigation findings and engineering context that should remain internal

Human approval remains the final control point before anything is committed or published.

Giving the agents a versioned BI repository

For this workflow to work reliably, the agents need more than just the dashboard itself.

The repository therefore brings together the main assets behind the BI environment:

• SQL and business logic

• mirrored Tableau workbooks

• published Tableau datasources

• dashboard documentation

• utilities for synchronization, lineage and publication

Tableau Cloud remains the source of truth for the dashboards.

Git provides a version-controlled representation of the assets around them, making it easier to inspect changes, connect dependencies and understand how a dashboard has evolved over time.

From Tableau to Confluence

At a high level, the target flow is: 

First, the latest Tableau workbook and its relevant datasources are mirrored into Git. The repository also contains the related SQL and dependency information, giving the agents the context they need to understand how the dashboard works.

From there, a documenter agent investigates the dashboard and produces the first version of the User Guide, Technical Documentation and, where useful, Internal Knowledge. A reviewer agent then checks the drafts for clarity, consistency and the right level of detail for each audience.

The result is reviewed by a person before anything is committed or published. Once approved, the User Guide and Technical Documentation are published from Git to Confluence, while the more detailed engineering knowledge remains internal to the repository.

This already gives us a repeatable process for documenting a dashboard from scratch. The next step is to extend that workflow to incremental documentation updates when documentation already exists.

Instead of reviewing or regenerating the whole documentation every time something changes, Git can tell us which BI assets changed — for example, a Tableau workbook, a datasource or a SQL transformation — while lineage helps identify which documented dashboards may be affected.

The workflow could then focus only on those dashboards and assess whether the change actually requires a documentation update. A visual layout change, for example, may have no impact at all, while a change to a KPI calculation could require updating both the Technical Documentation and the User Guide.

This is what I mean by incremental documentation updates: moving from “document this dashboard” to “understand what changed, decide whether the documentation is affected, and update only what is necessary.”

What I validated

I tested the PoC with real dashboards, which helped me adjust the workflow based on actual use cases.

Some of the main things I refined were:

• separating business-facing and technical documentation

• making sure the documentation reflects what users can do in the dashboard, not just its default view

• keeping detailed technical findings for the BI team without adding unnecessary complexity to user-facing documentation

• keeping the source documentation in Git while publishing only the relevant content to Confluence

• adding human review before documentation is committed or published

After testing the approach with users, I got the go-ahead to continue moving it towards production.

Why this matters, and what I learned

The value of the PoC is not just in saving time on documentation. Having BI assets in Git gives us a clear history of changes, while the agentic workflow reduces the manual effort needed to understand dashboards and keep their documentation aligned.

One of the main lessons was that giving an agent access to the right tools is not enough: the quality of the context matters just as much.

A Tableau workbook on its own only shows part of the picture. To understand a dashboard properly, the agent may also need its datasource, the SQL behind it, lineage information, existing documentation and shared knowledge about how the BI platform works. Keeping that context together in a structured repository makes the agent more useful and reduces the amount of information that has to be provided manually each time.

I also found that separating responsibilities works better than asking one agent to do everything. The documenter can focus on understanding the dashboard, while the reviewer focuses on clarity, consistency and whether the level of detail is right for the intended audience.

Finally, human review is still important. The goal is not to remove people from the process, but to move their effort away from collecting information and writing first drafts, and towards the areas where business context and judgement matter most.

These lessons go beyond Tableau. The same principles apply to many BI and data use cases: give agents reliable context, define clear responsibilities, and keep human control at the points where interpretation matters.

‍

Next steps

My next step is to keep testing the workflow with dashboards that have different structures and levels of complexity.

For now, I want to keep the process controlled: agents can investigate, draft and review, but final approval still stays with people.

Once the documentation base is large enough, the next challenge will be to automate incremental documentation updates: detect relevant changes in BI assets, identify which documentation may be affected, and ask the agents to review only the relevant parts.