Localghost
6 Apr 2019

Why software engineers should know their audience

When you’re talking about what you’re working on, do you ever stop to think about what you’re saying and whether the person you’re talking to can actually understand it?

There’s more to being a software engineer than coding. What people often underestimate are the so-called “soft skills” (the worst term for something that’s really vital) - the way that you interact with others around you. In particular, how you communicate what you’re doing to people with different skillsets.

Imagine you’re in a standup and someone gives this update:

I’ll synthesize the haptic DDR3 network, that should shut down the SDD capacitor!

This came straight from the brilliant Hollywood Jargon Generator, but to anyone who doesn’t have as much technical experience as you, that might as well have been what you just said.

u wot m8

One of the best pieces of advice I ever got was from a tech lead who took all of the engineers aside after a standup where we’d been discussing how we were getting on with the new authentication flow we were writing. She told us to make sure we didn’t go into too much technical detail in the standup, so that everyone could understand it. Sounds so simple, right?

We’d just spent ten minutes with the rest of the team - including our product manager and the marketing lead - and we’d been talking about refresh tokens and token expiry. It had meant absolutely nothing to several of the people there. The more we mentioned these arcane technical concepts, the less the rest of the team wanted to come along to standups because they felt it was irrelevant or above them in some way.

“But it’s a standup!” I hear you cry. “You’re only meant to give a quick high-level update anyway!”

You’d be surprised how easy it is to start talking in jargon without even realising for even the smallest of updates. Next time you give a standup update, ask yourself: if I weren’t technical, would I know what I was talking about?

Two characters are talking. Left: What've you been up to? Right: Doing tons of math for my thesis. Left: Can you explain it like I'm five? Right: Oh my God, where are your parents?
source: xkcd

How much technical detail do you really need to go into? If your standup tends to be “here’s what I did yesterday and here’s what I’m doing today”, do you need to say:

We’re still trying to get the auth service to store the user’s refresh token in the database and check it against the incoming requests.

or can you just say

We’re still trying to get authentication working in the backend.

To you the first example might look pretty easy to understand, but that’s probably because you’re an engineer. You know what a refresh token is. You know what a request is in this context. Non-technical folk probably knows what a database is, and what authentication is, but that’s about it, and they’ve switched off by the end of the sentence. By keeping the technical detail to a minimum you’ll be providing an update that the rest of the team understand, so they know what everyone’s working on.

What about if there’s a particular technical thing that’s blocking you that you wanted to mention in standup? Either mention that you’re generally blocked in the update and approach one of your fellow engineers afterwards, or maybe have a 5-minute dev-only standup after the main team standup where you can go into more technical detail.

Here’s another example:

Some of our ElasticSearch nodes went down last night, it turns out we are still using the old cluster so we’re going to migrate to the new cluster today.

vs.

Our search system went down last night, it turns out we’re using an old server* so we’re going to move it to the newer one today.

* I know this isn’t technically the same thing, but to someone who doesn’t know what a cluster is, it literally doesn’t matter. You can go into more detail in the relevant dev standup/slack channel/coffee break.

Use real-world analogies

Keeping your language simple works for technical people too. If you’re mentoring another engineer or helping someone work through a problem, being able to explain technical concepts in an easy-to-understand way and relating them to tangible concepts in the real world can really help others to learn from you. You’ll find it a useful skill for giving talks - there’s a real difference between “show me how” and “make me understand”. For example, in a talk about redux-saga I used pictures of dogs to illustrate the library of effects it provides. In pretty much every object-oriented programming language tutorial there is some kind of Person or Car class to help you understand the concept of an object, and the tutorials about composition and inheritance usually talk about different species of animals.

With the auth token example, I told my team a story about a secret members’ club involving an ever-changing secret handshake and a badge that let you learn the new secret handshake, which went down well and helped the others to get what we were trying to do, even though my product manager thought I was talking about a sex club.

Yeah, so we really need to reticulate the splines in our codebase

It’s not just standups where this skill comes in handy: in your day-to-day role, explaining technical things clearly and simply might be the thing that convinces them why you should take a break from delivering new features to go back and tackle the mountain of tech debt that’s been piling up:

We need to upgrade a lot of the packages, check for security vulnerabilities and replace a lot of deprecated code.

What does “deprecated” mean? What are packages in this context?

We’ve got some old code that needs updating because soon it won’t work any more, and it might pose a security risk.

It sounds so basic, but to a non-engineer, that’s all they need to know. They might ask some questions about what kind of risk it poses, or what “won’t work any more” means, but it’s a lot easier to follow.

Challenge yourself to keep it simple

It’s not always easy to translate the hard stuff in easy terms, especially when you’re working on things that involve kubernetes (true story). I still haven’t found a good layman’s explanation for what Docker does. But next time you’re in a standup, listen carefully to what your fellow engineers say and then catch up with your other team members afterwards to ask if they followed everything. If they say yes, then you’re fine, and you can just carry on as you were. But if they say no, consider getting your team to challenge themselves to deliver very simple standup for a a week. Make up ridiculous stories to illustrate migrating ElasticSearch clusters. At the end, ask those same people whether they feel like they know more about what you’ve been up to.

And if all else fails, there’s my old favourite fallback:

Everything’s slightly broken, but I’m working on making it not broken.

Back to top
24 Jan 2018

Things Experienced Speakers Wish They'd Known

Tips For First-Time Conference Speakers

Congratulations, you’ve been accepted to speak at a conference!

But once the initial euphoria wears off, you might find the impostor syndrome starting to set in. What if I’m not good enough? Do I know enough about this topic? What if the audience hates me?

That’s me right now. I’m currently preparing my first ever conference talk for ReactFest 2018, which I was encouraged to apply to by the excellent folk at ReactJS Girls London. Having gained quite a few new followers on Twitter after my talk was announced, I thought I’d canvas a bit for helpful hints for a first time speaker. I figured a few people might respond.

Just a few.

347 new interactions on Twitter
What a thing to wake up to.

I got so many fantastic tips and suggestions—including some from experienced speakers like Sarah Drasner, Dan Abramov and Anjuan Simmons — that one user suggested I turn it into a blog post. So here it is. (Thanks to @sayzlim for the suggestion!)

These tips have come from the tech community, but I think the majority of them can apply to any public speaking event.

Preparing your talk: Slides and content

You’ve got the outline of your talk that you submitted to the Call for Papers, but how do you turn it into a full talk? Whether your talk is full-length or a shorter lightning talk, it can be quite stressful when you’re deciding what should go in and what you should leave out.

Find someone with speaking experience to help you put together your talk. The organisers of ReactFest put me in touch with a lovely volunteer who offered to give me some pointers. Find a friend, mentor or colleague with experience of giving conference talks, and ask if they will help you out.

One thing that came up repeatedly on Twitter was the concept of storytelling. Rather than just listing ideas or treating the talk like a tutorial, you want to tell a story . This makes the talk so much more engaging, and more likely to be remembered.

When it comes to putting a deck together, most people tend to use Google Slides, Keynote or PowerPoint, but tech folks might also like to try out Reveal.JS, which lets you write fully responsive slides in HTML or Markdown (perfect for code snippets!). I used it for a talk I gave at a meetup, and had the entire talk hosted on GitHub Pages just in case I had to use someone else’s computer (which, in the end, I did!).

Once you’ve got the content nailed, you can focus on the design. Don’t worry about being too fancy — you want your audience to focus on what you are saying rather than what’s on the slides. Too many words on the slides will distract the audience, as will too many animated gifs! You can always create another version of your deck with more details on for sharing afterwards, as suggested by @henrihelvetica.

Keep your slide theme nice and simple, and consider whether the theme you have chosen will be easily readable from the back of the room with a crappy projector. Put your name and Twitter handle (if you have one) at the bottom of every slide because people will forget it if you only put it at the beginning (thanks @claireinez).

If you’re putting code in your slides, don't go overboard. Sometimes it’s inevitable — for example if you’re talking about how a particular tool or library works —but as @alexmcpherson suggests, it’s best to keep them short, 8–10 lines of code maximum. You can always share a repo or a CodePen link with your audience afterwards.

Practice makes perfect

Something that came up over and over again: rehearse your talk! Do it on your own, give it to your cat, make your colleagues listen to it and get their feedback. I got my fiancé to listen to my talk about redux-saga, and even though he didn’t know the content, he gave me some really helpful feedback about how I was delivering the talk. Your manner of delivery is just as important as what you're saying.

Local developer meetups can be a fantastic place to try out your talk before the conference and gather some feedback/see how it lands — a bit like how comedians try out new material in smaller venues before festivals and tours.

Rehearsing your talk will also help you to get a feel for how long it takes to run . Your talk will be strictly timeboxed, so make sure you get your key points across in the time that you have.

Don’t be tempted to script out your entire talk, as it’ll come across as a bit robotic (plus put a whole lot more pressure on you to learn it). Instead, become familiar with the key points of your talk and deliver those in a more improvised, natural way .

Technology isn’t always your friend

Make sure your talk works offline — you never know what’s going to happen. I’ve been to a tech conference before with no wifi or sockets for power. As @naomi_freeman suggests: “Don’t trust the wifi. Download any online content BEFORE travelling.”

Dan Abramov suggests having a backup of the slides online that will run on someone else’s laptop. Google Slides can be run from anywhere if you share the link, or you can host your Reveal.JS talk somewhere like GitHub Pages. Make sure you are comfortable giving your talk without prompts , as you might not be able to access your speaker notes.

If you can, find out beforehand what the setup will be like at the conference. The projector they are using, the size of the room and the equipment available will all affect things like font size, colour scheme and audio.

Don’t assume the organisers will provide the adaptor you need to connect your laptop! Bring it yourself just to be safe (and label it with your name so nobody steals it).

To demo or not to demo?

This was a bit of a divisive one — should you have a live demo in your talk?

A demo can be a fantastic way of, well, demonstrating a technical concept. But there’s always a risk that something will go wrong on the night — whether it’s down to nerves, technical issues or just plain bad luck. You can avoid this by making a recording of it beforehand that you can play to the audience and narrate what you’re doing. Or have a working copy that you can check out from Git in case of emergency (thanks to Laura Wilson for that tip).

Mac users can use Kap to record screen captures in video or GIF format. There’s also Kazam for Linux and CamStudio for Windows.

In some cases screen captures might even be better than live demos:

And as @fforres points out, don’t rely on your audience to be sensible — if your demo involves live input from the audience, be warned, people might send in something rude!

On the day

The dress code at tech conferences can be pretty casual, but if you’re wearing a dress, make sure it has pockets as you’ll need to attach a mic battery pack! @knitcodemonkey says: “Wear something with a collar and a waistband for the mic. Wear comfy shoes.”

Bring a water bottle and don’t forget to drink from it to keep your voice happy.

Take off your lanyard or any heavy jewellery before you go on, because microphones will pick up the sound of it rattling around.

Make sure your laptop is ready for the talk: close all other programs, have the slides up and ready, and turn all notifications off. Put your laptop on airplane mode if you can. If you have a smart watch or phone on you, don’t forget to silence that as well.

As you’re about to go on, you might feel the nerves. The audience is waiting! Take a deep breath and try to radiate confidence , even if it doesn’t come naturally to you. The audience won’t know you’re faking confidence (and soon you won’t be). You know your stuff, you love your topic, you’ve rehearsed it time and time again — you are ready . Enjoy it.

Be aware you might not be able to see anyone in the audience…

Move around a bit , rather than standing still behind the podium. It can be tempting to just keep talking — don’t forget to pause now and again.

Be mindful how you address the audience — don’t just fall back on “guys” considering your audience is likely to be a mix of genders (thanks @fforres). Jokes are a fantastic way of lightening the mood and keeping the audience engaged, but avoid any risqué/potentially inappropriate jokes.

Don’t be put off if you make a mistake! If you leave something out or stumble over something, nobody will know. Keep going!

And don’t forget the most important thing:

You’re at the conference because you love your topic, and so does everyone else there. You’re all on the same team. As @tlakomy assures me: “It’s going to be okay”.

Taking questions?

Sarah Drasner recommends not taking questions during your first talk:

That said, it’s a personal choice — if you feel comfortable (and time allows it) you can take as many questions as you want. An excellent tip from @bradwaynemartin: always repeat the questions back to the audience , as the microphone won’t pick them up.

But if anyone does challenge any decisions you made, you can fire this straight back:

Good luck!

To all first-time or aspiring speakers: you’ve got this!.

If you’re looking to get into the world of conference speaking, a great place to start is local developer meetups (if you can’t find one, start one!). You might even start by giving talks at work to your colleagues. The more you do it, and the more feedback you gather, the more comfortable you’ll become.

I also recommend taking a look at Jo Francetti’s guide to Public Speaking For Beginners and Emily Webber’s list of things that speakers need from conference organisers.

Thank you to everyone who contributed to the enormous Twitter thread that led to the creation of this post. If I have forgotten to credit anyone, or you would prefer not to be included, please get in touch.

Back to top