Good ad-hoc reports

22 February 2016

In my previous post, I wrote about hitting the right level of abstraction, especially when giving spoken, ad-hoc reports. While getting the abstraction level right makes a report more understandable and digestible, it is not quite enough. Let’s look at the example from the previous article once more:

Paul: “Hey Steve, by the way, what is the status of the staging server for the image generation? I heard that there is a delay.”

Steve: “Oh, yes, there are still some problems with it. On Monday, between the review meeting and the company presentation, we tried to find somebody from the operations team to help, but nobody was there. Apparently, they were all out at the data center, because there were some issues with servers overheating. Most of the guys stayed there the whole day. On Wednesday, finally, we could get hold of somebody to look at the server with us, and the logs were very confusing. The image conversion tool uses such a weird logging format where they put the date at the end, and the message in front, so to filter through them, we had to adapt our usual commands, and that also took us a while to get right. Also, there are different OS versions on the staging servers compared to our development environment. They run 5.7.41, and we run 5.7.39. The versions used to be the same, but they upgraded the staging environment last week, because tarbool wouldn’t run on 5.7.39, and they need tarbool to run on those servers. And while the Image Wizardry library runs fine on 5.7.39, it produces a segfault on 5.7.41 when you try to rotate images counterclockwise at an angle of 19.45 degrees. At least the logfiles suggest that. So that’s the current picture.”

Abstraction in action

The novel that Steve tells us obviously has some overly detailed parts to it, so let’s apply some abstraction to it, and see if that makes things better:

Steve: “Oh, yes, there are still some problems with it. On Monday, we tried to get help from the operations team, but they were all at the data center because of an emergency. On Wednesday, finally, we had a look at the logs with them, but the logging format of the image conversion tool caused us some extra work. Also, as of last week, there are different OS versions on the staging servers compared to our development environment, and the Image Wizardry library produces errors on the newer OS version under certain circumstances. So that’s the current picture.”

So, this is better, right? Better, yes. Good, no. Better, because it is much easier to follow, not as confusing, and much shorter. Good reports are as short as possible, while providing all the relevant information. The time I need to read the first version aloud is 55 seconds. For the second version, it is 27 seconds. Stripping away some extraneous detail brought us a 50% saving with practically no information loss.

Detours

But why is the report not good yet? Because there is still quite a bit of off-topic information in it. You might also say the speaker takes detours or gets sidetracked. More precisely:

The chronological order about what happened on Monday and what happened on Wednesday is probably of little interest to the listener. What’s done is done, and you cannot change it.
Moreover, what the operations team did on Monday is not, or should not be, the topic of this conversation. Maybe Steve remembers very vividly how everything was in a turmoil because of the data center incident, but right now, this is clearly a detour.
The problems with the logging format are a thing of the past. Again, what’s done is done, there have been some delays because of the logging format, but no one is going to change that, and it does not affect our current situation.

We could drop the respective parts and lose practically no useful information:

Steve: “Oh, yes, there are still some problems with it. We had a look at the logs with the operations team. As of last week, there are different OS versions on the staging servers compared to our development environment, and the Image Wizardry library produces errors on the newer OS version under certain circumstances. So that’s the current picture.”

Now, we’re talking. Cutting away some more fluff brought us down to 14 seconds, 25% of the original duration, while maintaining 100% of the relevant information, which is:

“The current software combination of operating system and image library causes problems.”

This is the core statement of Steve’s report, on an abstract, digestible level, and stripped down to a length that does not strain our attention span too much. So, are we done?

Think about the future, kids

Well, it’s called status report, and the statement above does describe the current status. However, status updates should usually answer two questions:

What is the situation right now?
What are the next steps?

Steve’s status report answers the first question, but he says nothing about next steps. Is anybody working on the problem at the moment? Who? Can anybody support? Which problems exactly are worked on? Is there an expected outcome to the investigation? Does Steve have suggestions how to proceed? Is there a plan B in case nothing works out? All these questions might circle around in Paul’s head, endlessly waiting for an answer.

Some possible additions to Steve’s report are:

“Simon is developing a patch for the library to prevent the crashes, but it will take him until tomorrow, at least.”
“We filed a bug with the developers of the image library, and they promised to look into it. But it will probably take a couple of days.”
“Peter is currently looking for instances of the same problem on the Web, but I’m not sure he will be able to come up with anything.”
“I think we should try to find a different image library that runs properly on our OS version. Maybe we could have a small meeting on the topic. Simon, me, and you? What do you think?”

In the last example, Steve asks Paul for his opinion and for a decision, which is exactly what a decision maker is there for. Now, everybody is on the same page, and further action can be taken. Maybe they will evaluate different software. Maybe they will pull resources from somewhere else. Maybe they will wait for a result from the library developers.

Summing up

Let’s reflect on what we have discovered. The problems with the original report were:

It was unnecessarily long, because…
…there was too much detail, and…
…there was a lot of off-topic information in it.
Last, but not least, it did not even answer the question properly.

We fixed those problems in several steps, and can give the following advice on reports:

Try to be short and concise.
Don’t lose yourself in details. Try to hit the right level of abstraction.
Don’t get sidetracked. Focus on the relevant facts only.
Don’t forget to inform the other person of the next steps.

You might think I’m overly strict here, or overemphasizing something very minor. However, in a high-stress situation with decision makers who are in a hurry, a good report can keep them from going totally insane or from grinding their teeth with impatience while you ramble on and on. Most importantly, giving good reports is very beneficial for you - it will increase the confidence and trust with which your boss relies on you, and make you his preferred go-to source of information.

Want to learn more on communication? Check this out: