In college I took a Computer Science 101 class. For the first assignment, the professor asked us to write step-by-step instructions on how to tie a shoelace. (Stick with me here.) I thought, “No problem. Just make the bunny and run around and go through the hole. Boom.” The next day he asked for volunteers. He read their instructions and followed them word-for-word in order to (try) and successfully tie a shoelace. It was comical. He never even came close to anything resembling a knot. Choreographing a knot in English is an almost impossible task. Seriously, try it.

Of course, my point in bringing it up is to show just how foreign it is for most of us to write good step-by-step instructions. And to illustrate how computer languages interpret commands: with zero interpretation.

When it comes to interactive and digital projects, like websites, apps, games, and so on, it is the job of a software engineer to read our instructions so that computers can get laces tied — and forms submitted and data sorted — without any interpretation.

How We Can Help Them

In this business you often hear the tip that engineers and developers should learn to speak in less technical and more plainspoken language. This is true. But I think it’s as important for non-technical people to learn how to communicate with technologists as it is for technologists to learn how to communicate with non-techies.

It’s not the job of Project Manager, Product Manager, or Marketing Manager to write code. Or to replace the brilliant technical minds on a project. But it is our jobs to create efficiencies and get effective software delivered.

Interactive project teams are always made up of technical people and less-technical people. Clients, project managers, designers, and others often (though not always) fall on the less-technical end of the spectrum, while developers, quality assurance testers, and software engineers are always (yes, always) on the technical end.

So how do we all get work done, together? Communication.

Communication is the key to every successful project of any kind everywhere. Good communication makes things go as efficiently, smoothly, and cooperatively as possible.

When I take the time to communicate specs in a way that helps engineers do their job more easily and more efficiently, we’re all in a better place. Plus it’s a great way to earn geek cred.

Speaking Geek 

When I first started working with engineers (whom I love), I often felt like I was dealing with robots, “Why are you asking so many questions? Why can’t you just interpret my foggy intentions and fill in all the blanks? Why is this so hard to understand?!”

Then I thought back to my Computer Science 101 days. And I realized that frequently what I, or a client, was requesting was equivalent to my shoelace tying instructions: well intentioned but fuzzy.

It often takes some back and forth to bridge the gap between an idea (Let’s make a form!) and the steps necessary to execute that idea as it was intended (What type of content can be entered into each field? Are there character limits? Where does the data go? How is the data stored? Can the user access their information later?).

That back and forth takes time. And time is money. But it doesn’t always have to – learning when to engage your inner robot-mode is a learnable skill: there are patterns to the questions engineers ask, and to the information that’s required to better communicate an idea.

Here are some key pieces of information that you should answer before you hit send:

  1. Intent. What is the desired outcome? What is the requester trying to achieve by asking for this feature or thing?
  2. Scenario. What is the user flow? What is each step that a user has to take to get the suggested thing done?
  3. Functionality. What confirmations, both user-facing and behind-the-scenes, will happen so that we know it’s working correctly? How will teams test whether the feature is working correctly?
  4. Usability. Based on the user flow, how does this thing need to work and look like on the most common screens (typically phones, tablets, and desktops)?
  5. Data. Does this thing collect data? If so, how do I plan on using the data or storing the information I’m gathering?
  6. Assumptions. Is every step, goal, outcome, and intent being communicated?

Geek Interpretation in Practice

Before

“Our client has requested a contact form that interested customers can fill out before they can access the Resource Library page. It should go on the Resource page and email them with the information.”

After 

The client would like to test if capturing visitor contact information before allowing access to the Resource Library section will help provide their sales staff with more qualified leads [intent].

To facilitate this we are proposing a form with first name, last name, email, and phone number fields (all required) be added to the /resource page under the current Resource Library call to action. The user must complete and submit the form to proceed to the resource/library page. The specific copy to appear with the form is TBD. [scenario]

Below are additional details on the form and preliminary functional requirements. [assumptions & functionality]

  • An error message should appear next to any field that is left empty or if an invalid phone number or email is entered.
  • The information should be captured and sent via email to xyz-contact@xyz.com. The data does not need to be stored in a database. [data]
  • Access to resource/library should be blocked to those who did not fill out the contact form.
  • People attempting to access the protected page should be redacted to the Resource page and receive a message indicating the form is required. Specific copy, TBD.

What We Get

The “after” contains so much more information for an engineer to work with, and gets the team much closer to the final product. And yet the “after” details don’t require more knowledge about technology, they simply require more thinking about how something should work. 

Whether you’re a client, represent a client, or frequently work with technically-minded colleagues, learning to think like an engineer is a win. And it’s not just a win for you – it’s a win for the entire project and team.