Enter The Conversation

“Always enter the conversation already taking place in the customer’s mind.” ~Robert Collier

Interesting quote. It comes from the sales and marketing world. Basically, it says that your message will be heard better/clearer if what you’re saying fits into what your customer is already thinking than if it’s disconnected.

That makes sense. Sure, sometimes a cold call really does pique your interest and get you to follow up. The more common response to a cold call, however, is to just say “Thanks. I’ll think about it.”, then promptly forget about the entire encounter. Which, as a marketer, is the exact opposite of the desired response.

It’s a good point, and it explains why targeted marketing is a thing and why the online advertising market is so big. Advertising your sneakers to someone who appears to be looking for sneakers has a much higher likelihood of turning into a sale than advertising your sneakers to someone who’s sad and is looking for a funny cat video to cheer them up.

What has that got to do with software though? Of course, it applies to marketing software. But it applies to UI design. And documentation. And API design.

Why are people using your API? They’re (probably) not using your API because they like you and using it is fun. They’re using it to get a job done. That’s where they are.

That means that your API is a conversation with your customer and that the goal of the conversation is to get the job done. Your API should be written in a way that makes it easier to get the job done. It should be consistent. It should speak your customer’s language. It should hide complexity, not create it.

The key is having the conversation at the right level of abstraction. Let’s say you’re writing an API that a website can use to display and manage a user’s travel schedule. The API you build will be somewhere between a single function that lets the user make a single SQL call and a single function that returns the HTML to be rendered. You could do either one of those, but the former is really the API you’re going to call when you write a new API, and the latter is what the website is supposed to do.

Instead, think of it from the user’s point of view. What do they know, and what do they want to do? They know the end user they’re dealing with. They know if they want to display the existing trips, show the detail for a specific trip, add a trip, or possibly change a trip. That’s the information that tells you what your API should do. It also gives you good info into what you should call the functions, what the arguments are, and what the return values should be. That’s the conversation you’re having with your customer. In their terms, in their language.

Just don’t forget Hyrum’s Law 😄