Communication is the key

One of our most important skills as programmers is that of communication.

At the most basic level, programming itself is a form of communication: using the language that you're programming in, the duty falls to you, the programmer, to effectively communicate your algorithms and ideas to the machine to have them executed.

Even if you have the smartest idea in your head, if you can't express that in your programming language effectively, the machine will never perform the tasks you expect of it.

This may seem like an obvious statement -- because it is.

What we often don't realise though is that the machine is wonderfully simple in its interpretation and often the languages we use are specifically crafted to facilitate the communication of our logical ideas to the machine.

People, on the other hand, are wonderfully complicated. And yet we still have the same duty to communicate with them, whether through the UX of our systems, or by presentation, meeting or via text in a post or email.

When we are learning to communicate our intent to the machine, we dive head-long into the language(s) we are utilising to perform that communication. We spend time learning about the features in ES6 (or the coming features in ESNext), we learn about lambdas and programming patterns which accomplish the goals that we have.

But how often do we stop to think about our tools of communication with the people around us? With our co-workers, our users, our bosses and team-members. The Pragmatic Programmer has some thoughts to help with this, but first, a small sojourn on a parallel track:

Code is for co-workers, not compilers

Now back to the learning from The Pragmatic Programmer!

Know what you want to say

Take the time to prepare the words you're about to express. Figure out your main points and the best order to use to get them across effectively and succinctly.

Know your audience

You'll have to prepare your communications differently depending on your audience.

If you're trying to advocate for the use of a new technology, you're going to need to convince management of how it will positively effect the bottom line. Will it directly save money? Will it save development time? Will it reduce support time?

If you're talking to developers, you'll need to convince them why it's better than whatever they are currently using. Does the new way perform way better? Is the tooling just amazing, leading to a glorious developer experience? Perhaps it's easier to bundle and deploy your applications? Perhaps you can write once, deploy to multiple targets?

Choose your moment

Trying to present your idea at the end of the day on a Friday, after a hard week, may not be the best idea. You're going to struggle to get people to pay attention. Similarly, asking your manager for a hardware upgrade when there's a major production issue is most likely not going to end favorably.

On the other hand, raising awareness of better source control methods when people are struggling with merges or lost code is likely to get people listening. Bringing up the idea of using Redis for caching when reporting shows that your servers are under heavy load is likely to go well.

Choose your style

Much like knowing your audience and the information which they will find most engaging, you also need to pick a style for the communication which is likely to get your point across and make it stick.

If you're dealing with your users or upper management, they may not be as interested in the technical details that make your plan amazing. They will, however, be interested in how your plan can save them effort, time and money.

If you're doing a more informal presentation for co-workers, I've found it's a good idea to include some lighter moments in your slides -- something funny every now and then can help to keep people engaged and interested.

Make it look good

There are myriad ways to produce presentations and documents, from DeckDeckGo to Google Slides to good old markdown!

People are more engaged when the content is pretty. It's a simple lesson we should learn early on whilst writing user-facing code: sure the functionality must exist, and it should be reasonably performant and bug-free. But if it's ugly, users will resist it. It's for this reason that it's definitely worth it to have a designer on your team -- for your product and for your presentation!

If you're not sure, just go ask a designer, humbly, noting that they do this for a living and are surely better at it than you are. Most people will help if they realise that they're not just being used, but are appreciated for their skills.

Involve your audience

If you're presenting, be sure to have a Q&A at the end, or even stop for questions at intervals. Even if you do the most informative, pretty presentation, if you lost someone along the way because you made an assumption about what everyone would understand, you're not being as effective as you could be.

Be a listener

Do you know what it's called when you talk and don't listen? A monologue.

Communication is two-way, by definition. Often the best communication is done by shutting the mouth-hole and opening the ear-holes! You have your piece you need to say, sure -- but what if your good idea simply isn't as good as you thought it was? What if someone in the room has that last killer aspect they could add to make your idea the absolute best?

I find it works quite well to admit that I've probably missed something, or to specifically engage people that I expect would know more on a subject, by telling them that directly. I especially do this when I want design input: I know it can be difficult to give your advice on something when you're talking to someone else who had this idea and is all fired up about it -- so I try to open that door first, by saying things like "What do you think?".

Often if I'm in a more confrontational exchange via email or GitHub commentary (read: defending my work), I'll lay out the why of my methodology and then append: "Your thoughts?". I want the discussion to be open because I've come to realise that if someone else stands up to me they must honestly believe that they have something useful to add -- and it's likely that I'm just missing that thing. It can be hard to take critique of our work, but we can learn and grow a lot more if we just listen a little more.

Something I've learned from feedback from a friend is that people digest your ideas better when they are in bite-size chunks. My takeaway: write shorter paragraphs! If I find a long paragraph, I try to find a way to break it up.

Use other methods like lists and headings on sections to also help people to work through your writings.

Get back to people

Always respond to emails, missed calls, Slack messages, whatever.

Note: you don't have to immediately respond to everything!

Sometimes you can't build a full response right now because you're focused on something else and you don't have the time right now. Something I've learned from watching software users is that people can be really patient if there is some kind of feedback. For example:

I watched how some people got frustrated with an app I wrote which would take 2-10 seconds to accomplish a task. The time couldn't really be helped: there was stuff that needed to get done, and that's just the time it took. However, if I put in some kind of progress feedback, I found that immediately users were way more patient.

Indeed, some research has shown that we will easily wait twice as long as necessary for a task to complete if there is feedback -- even if it's indeterminate feedback like a spinner!

So what you can do if you can't get back to a person properly right now, is to send a short message like "Thanks for contacting me. I need to gather some more information, but I'll get back to you really soon!".

Sometimes I find that I've only seen a message a few hours after it was sent (perhaps even the next day). I'm especially bad with this on Slack, because I turn off notifications so I can get work done. I know that if something is really important, a person will visit me physically or perhaps call me on my phone. I also know that a lot of people send Slack messages without really considering how they are interrupting other people. Still, if I see a message that I didn't get back to timeously, even if I've spoken with the person in the interim, and even if we've spoken about that very subject, I always send something like "hi, sorry, I've just seen this now! would you still like to chat?"

Keep code and documentation together

Documentation on how to use or set up a system can be invaluable, especially to a new developer on the team. I find that it's good to keep that documentation alongside the code. I start with the README.md file, and if that gets out of hand, create a docs folder and start putting more in there.

Mostly, we want to:

1. Make it easy to find the documentation -- if someone already has the code, why make them hunt down documentation in another system? If the documentation already exists in another system, at least create a README.md with links into that other system
2. Make it easy to modify the documentation -- when we change the code, if applicable, we should be updating documentation. Documentation which is not updated quickly becomes lies that are ignored by all.

Wrapping up

I know this is a bit of a long post. If you got this far, I thank you for your time. As I noted in another post I believe that we only really have two resources available to us which are truly ours: our bodies (which includes our brains and the concept we call "mind") and time.

One of the guiding principles of communication should be a respect for the time of people you're communicating with. Every minute you take of that time can never be refunded or regenerated. We have a finite amount of the stuff, and, best of all -- we don't know how much!

Try to keep your presentations long enough to be fully informative, but short enough that the time you've taken from the attendees was well-spent. When you're writing or presenting, you're asking several other people (perhaps even hundreds!) to give up their time to hear your ideas. Be grateful for those people who attend and give feedback!

Namaste.