DEV Community

Jono Cairns
Jono Cairns

Posted on

Describing technical details to non technical people

If you’re a software engineer it’s almost certain you’ve had to do this at some point. Explaining why a seemingly small UI change will take weeks, or attempting to explain why switching frameworks is a good idea, is a struggle we have all run in to, or will eventually run in to at some point.

I’m by no means an expert at this, but it’s an issue I have grappled with my whole career, so I’ve compiled a list out some things that I’ve found useful in this process.

  • Establish trust with management or other areas of the business.

Why is this important? People need to know you back up what you say. This means estimates are relatively close, deadlines are met and even things like showing up to meetings on time is the norm. This may seem like a no-brainer, but I do feel people get a bad rep in our community for failing to do any or all of the above. The way I navigate this area is to set expectations early and overestimate things I’m not entirely confident about. This involves things like making sure you’re on the same page in terms of scope and context, as well as establishing what value this particular feature brings to the company. It also means keeping yourself honest and being OK with not knowing everything. If you are truly not sure about how long something takes, then add a larger variance for the timeframe.

  • Use applicable metaphors to get your point across.

Metaphors provide context even when there is extreme complexity in a particular topic. It also means you understand a problem well if you can condense and simplify it to anyone. An example I had a while back was when I worked at a company similar to hello fresh. The week to week software was constantly worked on, and worked well. When Christmas time came around the orignal developers were rushed for time and just copied all the table structure for the week to week processes and prefixed them with Christmas. This technique wasn’t changed for a long time because it just worked. The downsides started showing over time where bugs started to happen and the prep time for Christmas required a full time engineer for at least a month to get everything ready. My metaphor for this situation was we had two paths to deliver food to people, one I liked to call a super highway - this was our week to week BAU process. The other was an old walkway that hadn’t been resurfaced in a while. In my description I was saying the flow of traffic and size of the trucks going on it were getting bigger (attempting to describe scale here) and the old pathway just wasn’t handling the load. My proposal involved moving the Christmas system over to the week to week system as it was essentially the same. The only difference being the products for a specific week. So we had this super highway we could now send our Christmas trucks on this same highway. It’d get the benefit of being worked on and updated during the year, meaning any resurfacing and widening needed for upcoming Christmas traffic was already done. It also wouldn’t require someone to work full time clearing the path on a separate, inferior road each year.

  • Articulate and be confident in your reasoning.

This one is a tough one for me and I find words escape me regularly. Things that help me with this is adding pro/cons lists or even building technical documents that go through all the reasoning for a specific approach. In the technical document it’s good to keep a simple tl;dr for each of your main points then have a couple of paragraphs with the actual background, context and reasoning so if people push you for more info you can easily push deeper. This makes people a lot more confident in you as well as it shows you know what you’re talking about. You won’t look like a big tech leader at a senate hearing just saying “I’ll need to get back to you on that one”.

In conclusion this is a very hard part of our job and will only get harder the longer your career progresses. There is a lot of value in trying to see what methods work for getting people on board with your ideas. So far I’ve been over trust, using metaphors and citing research as key parts of helping in this area. What things work for you? I still consider myself a newbie in this area so keen to hear what other people have to say.

Top comments (0)