This is the first of two articles on spoken, ad-hoc reports. Jump to the second part.

Have you ever walked away after someone explained something to you, and you had a big question mark over your head? With no clear picture in your mind? Instead, there is an indistinct, cloudy, and blurry mess of would-be information that you can hardly connect to anything in the real world? I know that I have felt like this multiple times. For example, look at this dialogue:

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.”

Did you manage to read through this entire unstructured blob of words? If you did, and you’re like me, you probably found it to be a painful exercise, because there are some serious problems with this report. One of them is that it is way too detailed. Details have their merit, but in quick, ad-hoc reports, you should be careful how much you put in there.

Speaking of ad-hoc reports: While giving good written reports is certainly important, I will be talking about oral, ad-hoc reports in the following. I think there are certain unique things that can be observed in them.

Too much detail

So, there is supposedly too much detail in the report above. Let’s look at some evidence:

• “They use such a weird logging format where they put the date at the end, and the message in front, …“ => Certainly a curious logging format, but this piece of information is way too fine-grained.
• “They run 5.7.41, and we run 5.7.39.” => I would not expect any listener to remember (or want to remember) such detailed information as exact version numbers, and it does not improve a decision maker’s situation.
• “…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.” => The upgrade is a fact, and will most likely not be reverted. Therefore, knowing the exact reason is probably of no use.
• “…produces a segfault on 5.7.41 when you try to rotate images counterclockwise at an angle of 19.45 degrees.” => Again, too much detail. “… produces a segfault under certain circumstances” would probably suffice.

The “exam situation” syndrome

I gave similar ad-hoc reports on several occasions when I was starting out as a developer, and I think it’s a common pattern among juniors. When you’re inexperienced or insecure, you think that providing a lot of technical detail makes you appear competent and knowledgeable. Maybe you tell yourself:

“Uuuuuh, this guy is the lead developer, and of course the lead developer knows everything to the last detail, otherwise he could never become lead developer, right? My knowledge is being tested. I have to demonstrate my deep understanding of the situation by presenting as many facts as possible.”

In other words, a superior coming up and asking you for some information causes you to flash back into school or university days, and you feel like you are in an exam situation, where you have to give an A+ answer or you get a bad mark. The difference to university is, however, that the other person is not your professor, and he does not even know the correct answer. He can only judge, once he has received it, which kind of answer is useful to him, and which kind is not. It is your job to deliver an answer that fits the first category.

Context differences

While the exam situation syndrome is most common with rather young devs, there is something which is commonly exhibited also by more experienced people and which you might call context disregard.

In the context of the person who is reporting, all the details are well known, because she has been dealing with this project, task, or subject matter for days or weeks. However, not everybody will be as familiar with these details, of course, because other people have a different working context. Unfortunately, the reporting person disregards this fact, or does not bother thinking about it. In any case, they fail to make their report digestible to the other person.

A typical symptom of context disregard is using a lot of technical names, terms, acronyms, and maybe even self-invented terms that are not generally known:

Manager: “Do we have automatic testing for JavaScript yet?”

Developer: “Almost, we’re on the way. Currently, we are weighing Mocha against Jasmine, and we’re not sure if we should use Sinon or something else. But we have already decided on Karma, and on Wallaby.js for the IDE.”

Unless the manager has a very good overview of the vast number of JavaScript tools, she will not get a lot out of this answer. A better answer might be:

Developer: “We have picked some, but not all of the components of the testing set-up. Two software choices have yet to be made. I expect we will be done with our evaluation by the end of the week.”

That’s very high-level, without technical details or name-dropping, but all the relevant information is there: We will be ready to write automated tests by the end of the week. If the manager wants to know more details, she can always ask follow-up questions, but for decision making like planning and scheduling, this is probably all she needs.

The tunnel syndrome

Certain situations make it harder than others to give good ad-hoc reports. If you have just been thinking hard about something, organising dozens of pieces of information in your brain, and the next moment somebody walks up to you and pulls you out of your tunnel, asking for some status – well, you might find it hard to give a concise, to-the-point report that avoids all irrelevant details (point the person approaching you like that to Maker’s Schedule – Manager’s Schedule by Paul Graham to show why this should probably be avoided).

On the other hand, if you are relaxing in the kitchen over a cup of coffee, it might be easy to remember the requested facts and filter them according to relevance.

Hitting the one right level of abstraction

So, if putting too much detail into a report is the problem, the logical recommendation is:

• Don’t lose yourself in details. Try to hit the right level of abstraction.

Hitting the right level of abstraction implies two things:

1. Staying within one level of abstraction
2. Staying within the most useful level of abstraction – you don’t want to go too low, but also not too high.

Let’s look at the JavaScript testing example once more. Originally, the sender stays mostly within one level, but it’s not the most useful one:

“Almost done, we’re on the way.” => Abstract information: work is in progress

“Currently, we are weighing Mocha against Jasmine, and we’re not sure if we should use Sinon or something else.” => Concrete information: Names of actual software products under consideration.

“But we have already decided on Karma, and Wallaby.js for the IDE.” => More software product names

Except for the rather abstract “work in progress” information, this status report loses itself in the depths of too much concreteness. What are the mentioned software products actually good for, what is the relationship between them? These questions might pop into our heads, but remain unanswered. Let’s look at the improved version:

“We have picked some, but not all of the components of the testing set-up.” => Abstract information: there are multiple components to pick

“Two software choices have yet to be made.” => Abstract information: Two components to go

“I expect we will be done with our evaluation by the end of the week.” => Abstract information: time estimation

This improved report stays entirely within a rather high abstraction level. Of course, you could get even more abstract and say:

“We are about 60% done with the test set-up, and expect to be at 100% by the end of the week.”

Depending on your boss’ preferences, this might also work, but it feels a bit robot-like to me, like you’re a walking progress bar. Therefore, I find this abstraction level too high.

A crucial communication skill

In my opinion, hitting the right level of abstraction is a crucial communication skill. It is useful in all kinds of conversations in your professional life, in your private life, when dealing with higher-ups, when dealing with people you have just met, when instructing people, when giving presentations, and a lot more.

In professional settings especially, most people are busy and don’t have a lot of time. If you start out by narrating every detail of your current context – like the version numbers or the structure of the log file format above – you effectively waste their time. Moreover, you, the sender, do not put any effort into your message encoding and formulation. Instead, you put a heavy decoding and filtering burden on the receiver, which is mentally straining.

Implications

As a consequence, your listeners will become impatient and unwilling to listen any longer. Their thoughts will wander, and their attention suffer. Your superior will not enjoy reports you give him, and perceive them as unclear and unreliable. Depending on the outcome of your work, or your personal relationship, he might even suspect that you are hiding something behind your fog of words. At some point, this might cause him to stop asking you for reports, and instead ask somebody else – certainly undesirable for you.

To stop this from happening, you have to cater to the needs of your audience. Think about what is necessary and useful for them to know – and, quite as important, what is not. Put yourself in their shoes, and filter your thoughts and your words accordingly. Your message will be much easier to consume, and your conversational partner will be much more inclined to ask you for information in the future. People who are sought-after to inform management gain influence and appreciation – a good thing, needless to say, if you want to advance in your career, or if you want to actively shape your working environment.

As a final note: To some degree, it might be a matter of taste how detailed an ad-hoc report should be. Different managers will have different preferences. However, if a decision maker dealing with a tight schedule and information overload wants to be efficient, she will have to cut away the fluff that conceals the actually useful information. Therefore, I believe that most managers will appreciate short, to-the-point reports.

Read on to learn more on what constitutes good ad-hoc reports.