How to Specify a Report

March 30, 2014

When asking a developer to create a new report or dashboard widget, it's crucial to explain what you want in a clear and unambiguous way. Otherwise you won't get what you wanted and relations between you and your developers may even become strained as a result. Being clear about what you want is harder than it sounds though. While in your mind it's obvious what you mean, to others it is not.

I've seen many requests for reports that are confusing, or vague. Some contain too little detail, others contain the wrong kind of details, but after years of being on both sides of the fence, I'll give you the secret to defining reports to ensure you always get what you want:

Start With The Question

All reports exist to answer a high level question or to provide some actionable insight to their users. Start by setting the scene and telling the developers what this is. It could be as simple as "this report is designed to show which ads are performing better than others" or "this report will show us how much the products we shipped today cost us to make". Giving you developers this context will help them make decisions and provide a framework to fit all the other parts of your requirement on to.

Paint a Picture

I'm a huge fan of Balsamiq for design mock ups, but there are many similar wire-framing tools out there. They all provide you with the means to quickly and easily sketch out what you think the finished article will look like. Drawing what you think your report will look like gives you developers something they can hold up against the actual report and saves everybody a lot of time.

Stick to the Point

If you're getting a report built, it's tempting to throw as much information in there as you can, just in case it's useful later on. I'd avoid this if possible. I appreciate that sometimes you don't know what you might need right now, and that getting approval for a new report later on can be painful. But adding lots of extra bits of data to a report not only slows it down, it'll increase the chances that the developer gets confused building it, or that someone else gets confused while reading it.

Use Common Building Blocks

All reports have the same basic building blocks, if you learn what these are then you can practically define the report you want using a short hand notation:

Tables, Columns and Rows

Describe each table, does it have a fixed number of columns/rows? Does it show one row/column for each instance of something (e.g. "Order") in the database?

Groupings / Aggregations

Sometimes, one row or column on a table refers to a group of things. For example, a table may have a row for each year, with the values on that row coming from adding up all the "orders" in that year.

Charts / Maps

Is it a bar chart, pie chart, line chart, pin map or heat map. What's on each axis, what data series are there?

Parameters / Settings

Will the user be asked to input anything or pick from a list of options? Where do those options come from? When they do pick something, how does that affect the report?

Bringing It All Together

Here is an example of a report specification that includes all those elements:

The Commercial team require a report which will allow them to compare last years revenue forecast with actual revenue this year, and will show them whether they are still on target.

The report will feature the following:

  • Parameter: drop down list labelled "Forecast" showing a list of forecasts held in the database
  • Parameter: date picker labelled "start date"
  • Parameter: date picker labelled "end date"
  • Table: with one row per calendar month starting at the start date parameter and ending at the end date parameter. The columns will be as follows:
  • Column: forecast income, with each cell coming from the revenue forecast in that month according to the forecast selected in the first parameter.
  • Column: actual income, with each cell value coming from the total value of sales in that calendar month.
  • Line chart, showing the data from the table, with time on the horizontal axis and each column being represented as a separate line.