A few days ago I was summoned to a meeting where one of the most basic ideas a web programmer can have wasn't obvious to our non-technical customers. Something had gotten lost in translation, and now I had to try to explain myself.

A mistranslated sign, reading "Please Steek Gently"

Our customers (let's call them Kate and Harold) wanted us to develop a web site that would allow users to type some answers into a questionnaire on a webpage, then take those answers and insert them into a PDF document that would be placed in their document database. We needed to keep these questionnaires for review later by our internal auditing group. All of this was completely doable, since we already had the PDF document template that we could insert values into.

While the programming group and the customers had had some emails being flung back and forth, discussing the various ways we could implement the system they wanted and the amount of time it would take, something just wasn't clicking for the customers. It should be said that this group of customers is very non-technical, and so they called a meeting to ask us programmers (specifically me, being the lead programmer on this project) some questions about the kinds of things we could do to implement this questionnaire system.

The meeting went pretty well for the first twenty minutes or so. Then, Kate started asking about what would happen when the content of the questionnaire changed:

KATE: So what would happen if we added a question to the questionnaire?

ME: Well, we'd need some time to work up a new template and add the question to the webpage.

KATE: That takes too long. Can't we set up the tool to allow us to just edit the webpage ourselves?

ME: We can certainly do this, but I'm not sure why you would want to. You want to be able to edit the questionnaire?

HAROLD: That's correct. We can incorporate changes a lot more quickly than we can now if we have this. How long would it take to set this up?

ME: Not too long I think, since we already a foundation for this kind of change in place.

KATE: Perfect!

HAROLD: Let's just be clear about this. You're going to enable us to edit the questionnaire, and the changes that we make will be in the document that is submitted to our document storage, right?

ME: ...That's why I said I wasn't sure why you wanted to do this. We can certainly enable you to edit the questionnaire on the webpage, but that doesn't automatically mean the changes you make will be included in the PDF document; we would still need to write some code to do that.

HAROLD: I thought you said you already had the foundation for this in place.

ME: We have the part that allows you to edit the webpage, yes.

KATE: So we will be able to make changes to the questionnaire?

ME: Yes.

HAROLD: I must be missing something. If we can modify the questionnaire, and you already have the foundation to do that, why does the programming team need more time?

ME: (annoyed) Because we still need to write code to make the appropriate changes to the PDF document.

KATE: But why do you guys need time to make those changes if you can already allow us to edit the questionnaire?

ME: (realizing the problem) Because the webpage and the PDF document are not the same thing.

Apparently this was news to them. It was not obvious to them that the webpage and the PDF document were not the same thing, that we programmers still had to write code to keep the webpage and document in sync. Further, I repeatedly failed to draw that connection and explain it to them, and just kept repeating myself using different words.

My immediate reaction was to be annoyed. Seriously, I thought, that's so basic! A webpage and a PDF document are OBVIOUSLY not the same thing! My annoyance faded quickly, though, because I realized that I was expecting non-technical people to know technical details.

Let's face it: customers don't give a crap about the code. All they care about is "click here, type this, submit that, done," and frankly that's all they should care about. I had incorrectly assumed that something that was obvious to me would also be obvious to them, and because of this assumption, I had failed to properly communicate to them the amount of effort it would take to implement the process they desired.

This miscommunication between technical developers and non-technical customers is a gap that I've seen a lot of programmers (including myself) fail to bridge: we're so caught up in the details of an application that we forget that not everybody knows what we know.

My old self, the one that was locked in an ivory tower, didn't see any reason to be able to communicate with customers. After all, that organization employed project coordinators, people whose job it was to communicate back and forth between the programmers and the customers, and I was perfectly happy to let them handle the customers' inquiries. It wasn't until I accidentally ran into one of these customers in the hallway (and utterly failed to explain to him what it was that I was doing) that I realized I should be putting more effort into my communication skills.

Communication skills are essential for programmers. I believe we should always be able to explain ourselves to both technical and non-technical people. At some point in our careers we will be placed in a situation where we need to explain our code and logic to a non-technical customer. If we can do this in a way that they end up understanding what we are saying without needing to know any technical details, then we've bridged the communication gap. If we can do it repeatedly, then we've become more effective at communicating than many developers out there.

And, hey, if you find yourself at a meeting similar to the one I was summoned to, maybe you'll be able to explain yourself better than I did.