A report without explanation does not get used

The delivery of a dashboard often comes with a manual. A document of ten or twenty pages, with screenshots, arrows and an explanation of every button. It is neatly emailed, and then never opened again.

That is not unwillingness. Whoever does not understand a number does not go looking in a PDF from three months ago. He calls someone, or he ignores the number. Both are bad for the report.

Documentation and explanation are two things

There is a difference between documentation and explanation, and they are often confused.

Documentation is for whoever builds and maintains the report. Where the data comes from, how it is processed, which choices were made and why. That belongs with the code and the model. It is what made the third app the fastest.

Explanation is for whoever reads the report. What does this number mean, how do I read this chart, is this good or bad. That does not belong in a separate document. It belongs on the page, where the question comes up.

Three questions every page should answer

Every reader asks the same three questions about an unfamiliar number. Answer them up front and you avoid most phone calls.

What does this mean? Revenue with or without VAT? Margin after or before discount? Active customer by which rule? One sentence is enough. Put it in a tooltip on the number, or in a small info icon next to the title. You should already have agreed on the definitions, so it is copying, not reinventing.

How recent is it? When was the data last refreshed? This is the most underestimated question. A number from yesterday and a number from last week look the same. Show the last refresh visibly on every page, with date and time.

Who do I contact when it is wrong? A name, an email address, a button. Whoever sees an error and does not know where to take it stops trusting. Whoever does know where to go reports it, and the report gets better.

Explain the dip before anyone asks

Every series of numbers has dips. A month where revenue drops, a week with an outlier. Sometimes that is a problem. Often it is known: a refurbishment, a public holiday, the summer shutdown, a promotion last year.

Whoever does not know that gets a fright. A short note on the chart, at the point of the dip, prevents it. The article on data storytelling has an example: a sharp drop in July that was simply the construction holiday.

Make contact easy

The easier it is to ask a question, the better the report gets. That is an underrated mechanism.

A button on the page that opens an email to the person responsible, with the report name and page already filled in, costs little. The threshold to report something drops enormously. And every question that comes in tells you something: which number is unclear, which definition is wrong, which page is not used as intended.

After a few months you know exactly where the explanation falls short. That is worth more than any survey.

What you leave out

Explanation on the page has to be short. The goal is that the reader finds his answer without leaving the page, not that he gets a course.

• No explanation of how a filter works. Whoever uses the report knows that after once.
• No blocks of text above a chart. A title that says what the chart shows does more.
• No explanation that is only interesting to the builder. That belongs in the documentation.

A manual is still fine

This does not mean a manual is useless. For a new employee seeing the report for the first time, a short tour is useful. But keep it short: one page, or a three-minute video. And make sure everything in it can also be found on the report itself.

What you can automate

The time of the last refresh can appear on the page automatically, from the loading process itself. The definitions stored as descriptions in the data model can be shown automatically in tooltips. The contact button is a link that passes along the page and the report. And if loading fails, the process sends an alert itself, so you know before the reader notices.

The claim

A manual nobody opens explains nothing. Put the explanation on the page: what the number means, how recent it is, and who you call when it is wrong. Then the report gets trusted, and every question makes it better.