Evidence

A different shape of output

Most reporting tools produce dashboards: a grid of panels, interactive, viewed inside the tool.

Evidence produces documents. A page of written explanation with charts and tables in it, published as a website.

That difference is the first thing to weigh, because it decides whether the tool suits the requirement. For a reader who needs to explore, a dashboard is right. For a reader who needs to understand something somebody worked out, a document usually is.

Pages are files

A report page is a Markdown file. It contains three kinds of thing mixed together:

• Written text, explaining what the figures mean.
• SQL queries, each given a name.
• Components, which display the result of a named query as a chart or a table.

The page is therefore self contained. The narrative, the queries and the visualisations are in one text file.

What being a file changes

Because pages are files, the whole reporting layer sits in version control.

Changes are reviewed. Altering a report is a commit that somebody reads before it is merged.

History exists. When a figure in last quarter's report looks wrong, the version that produced it is still there.

Reports are testable in a branch. A restructured report can be built and viewed without anyone else seeing it.

None of this is available when a report lives inside a tool's database as a set of saved settings.

The query is visible

Because SQL sits in the page, the query behind any chart is right there.

This addresses a persistent problem with reporting: somebody asks how a number was calculated, and answering means opening a tool, finding the chart, opening its definition and reading a query nobody has looked at in a year.

Here the answer is in the file next to the chart. That makes reports auditable in a way that is otherwise difficult.

Explanation alongside figures

Charts show what happened. They do not say what it means or what should be done, and that interpretation is usually the valuable part.

Because a page is Markdown, the commentary is written directly around the charts. A reader receives both, rather than a dashboard and a separate document that has already drifted out of date.

Publishing

Building the project produces a site, served like any other website.

That has a consequence worth noting: distributing a report to a large audience is a hosting question rather than a licensing one. There is no per reader cost and no platform for readers to log into.

Who Evidence suits

Evidence suits analysts and engineers comfortable with SQL and text files, teams that already work through version control, and organisations producing recurring written reports where the explanation matters as much as the figures.

Points to consider

Authoring requires SQL and editing files, so it is not a tool for business users building their own content.

The output is also not interactive in the way a dashboard is. Where readers need to slice data themselves, this is the wrong shape and a business intelligence tool is appropriate.

There is a build step, which means a report reflects the data as of the last build. How often that happens is a decision to make deliberately.

Getting started

The documentation covers creating a project, connecting a data source, writing a page with a query and a chart component, and building and deploying the site. Producing one page with a single query and chart demonstrates the whole model.