In a recent iteration review meeting, the team discussed with the customer the progress made over the previous three weeks. In these meetings, we also discuss risks and demonstrate what has been accomplished.

The Enthusiastic Developer

Sometimes, the work performed is on the background functions; while it affects the user interface, it’s not something the developers can demonstrate through the interface. In this particular meeting, one of the developers explained the theory behind something that was very technical in nature and happening behind the scenes.

Developers are great, and they do some amazing things with code—especially the developers I work with. But I think that sometimes they fall into the same mindset that we all do from time to time, namely that because they are extremely interested in what they’re doing, everyone else should be too.

The Less-Than-Enthusiastic Audience

This customer is normally very energetic and has a quick sense of humor. I noticed while this explanation was proceeding, the customer—to whom we were connected via video conference—appeared to be losing focus. When the developer asked him if it made sense, he responded with a barely audible monosyllable. It was very unlike him. He seemed to come back to life a bit after the explanation was over, and the meeting ended soon after that.

The What Is More Important Than the How

I relate this not to poke fun at developers, rather because it emphasized to me a principle that’s important for technical communicators: The audience doesn’t always care about how things work. They care more about what they need to do to make it work and that it works.

It can be the coolest database acrobatics ever conceived, but if it’s not going to in some way help the user, it’s superfluous information to them, which means information that dilutes and gets in the way of the important information. And believe me, I’ve had a developer explain some database functions that were pretty sweet in their ingeniousness and required intricacy.

It can be easy to provide information to users about how the product works, about why it behaves the way it does. I wouldn’t call this a trap, but whatever it is (a puddle?), I fall into it myself. Some information just doesn’t make sense if you don’t explain the how. For example, in some release notes I’m working on, I’m including a known issue about the way a certain field behaves. I suppose I could explain only what they need to do to get around the problem, but it’s hard to do without providing a bit of the why the problem is occurring. As I think about it, I’m sure it’s possible to explain just the what and not the how and why. But that’s the dilemma I’m in.

Still, that customer’s sagging head during the explanation comes back to my mind. It’s not that the developer’s explanation in and of itself was particularly technical—at least not overly so, because he was deliberately trying to compare it to something easy to understand—and he even tried to involve the customer in his comparison. But it still came down to the fact that he was discussing something that was beyond the realm of relevance for the customer.

Wrap-up

Information about how things work has its place, certainly. But it’s usually off to the side or at the end in some appendix-type spot. If you find yourself including the how, try taking it out and putting it off to the side or at the end. Then go through the text without the how in there and see if it still makes sense. I’m betting that in most cases, it will. So I’ll be trying that myself to see if it’s a way to tighten up the content.

Related entries:

Tapping into the Resource of Project Documentation

Important Players in the Content Review Game

Three Ways to Get Developers to Keep You up to Speed

Minimizing Confidential Content in Documentation Images

“If an App Is Designed Well…”