Technically… no, it’s not that technical.

In the vast world of computer science, it is becoming way too faddish to boast that something is “technical” even when it’s not

Olly Akanni
Technical Writing is Easy
6 min readJan 8, 2023

--

See? Dilbert feels our pain.

The Double Standard of Dentists vs. Developers:

When you go to the dentist, and they tell you that your tooth 14 has a cavity, you probably don’t say, “You’re talking too medical.” You know that the dentist uses medical terms to discuss a specific tooth problem. Even if you don’t know all of the medical terms and procedures used in dentistry, you know that the dentist is using them to tell you important things about your dental health.

But if someone tells you that an interface isn’t working, you might be more likely to say, “You’re talking too technical.” This phrase is a natural reaction when we don’t know how a system or task works or don’t understand the technical details and steps. But it’s important to remember that technical experts use specific technical terms to talk about the systems and processes they work with, just like a dentist does when they need to tell you something important about your dental health. By dismissing these terms as “too technical,” we risk oversimplifying or misunderstanding necessary technical details and issues.

While the prospect of someone picking at your teeth is a huge motivator to pay attention, the point of that illustration is that there’s a societal expectation that you overcome any medical knowledge gap with questions and clarity.

The same should happen in the world of computing.

Oversimplifying Language is a No-No:

The irony of oversimplifying technical language is that while it may seem like a way to make complex concepts more accessible, it can often lead to misunderstandings and confusion. This point is particularly true regarding the technical aspects of computing, which can be difficult and nuanced.

For example, in a corporate meeting at a software company where someone describes “synchronization errors occurring in our landing zone,” the scrunched faces of leaders as they try to decipher the language indicate that the language used is too vague or ambiguous to be understood. The issue may be as simple as forgetting to put a file in a folder. (I bold that because it happens a lot more than people think.) But the oversimplified language used to describe it has led to confusion and misunderstanding.

This scenario is a common problem in computing, where technical language and concepts are often oversimplified to make them more accessible to a non-technical audience. While this may seem helpful, it can create more confusion and misunderstandings than it resolves. To avoid confusion, it is essential to use clear and precise language to describe technical concepts and processes and to provide explanations and context to help others understand the technical details involved.

Software Articulates Constraints and Limitations:

At my workplace, the terms “technicals” and “functionals” play out as if they are the yin and yang of two separate entities. Functionals can sometimes be intimidated by the specifics of how data flows. We are ultimately building software, and ironically, the specifics are often tied to software, and that software represents your constraints and limitations. While databases and the software used to interact with the database have been commonplace at my work, I get shocked at the number of people who want no part in knowing the specifics of the software used to build their applications. I’ve even been told by another self-touted technical, “why does the software matter?”

Just think: if you are writing a paper and know that spell-checking is a requirement, it is crucial to see if you are using software like Microsoft Word or a minimal program like Windows Notepad. If you are familiar with the capabilities of Notepad, you would know that it is challenging to spell-check a document using that platform. If that made sense to you, and you feel you don’t know anything about computers: congratulations. You just thought through something that is really at the forethought of every developer: how is this actually going to be done in software?

In some capacity, you have to use software to build software. Whether it is Visual Studio Code, Sublime, and some coding language compiler, or it is some sort of point-and-click visual development like what is found in Adobe’s Creative Cloud and others. Developers have to figure out what capabilities exist in their software and language choices and whether they can be stitched together to meet the needs of the product they are developing.

Show The Magic:

And therein lies the secret to demystifying technical processes: being able to visualize what someone has to do. That may be why we’re willing to endure the dentist’s jargon: we can’t escape the clarity of what they are doing. Even if we don’t understand everything, we can get a sense of just how challenging it may be.

On the other hand, programming is much like how hamburgers were made at fast-food restaurants in the 80s, in back kitchens you can’t see.

There are ways to overcome these gaps, whether it be education or just showing people the screens you use to do your work. There’s a lot of protective behavior that is usually found as a way to try and legitimize the value of what is being done. But rest assured, Technicals, even if there is an interest, the desire to look at thousands of lines of code isn’t everyone’s dream. You won’t be minimized by having clarity with your leaders.

Give Leaders An Honest Picture:

The reason any of this is important is that when leaders make decisions, you want them to understand what’s truly happening. And we have to accept in the technical field that we’re not doing something new. Lawyers, doctors, and dentists all share highly complex ideas with us and offer us decisions. We accept a degree of technical jargon insofar as we still feel we’re being given an accurate picture of what is happening.

Too often, the tech-sphere betrays its leadership by making it appear as if there is mysticism in its language and doing things like calling folders on shared drives “landing zones” and “data entry points.” We’ve got to do a better job of just being straight shooters in what we’re talking about. Otherwise, we’re going to be in some weird world where we call breakfast a “nourishment activity.”

What do you mean I didn’t say Hi?

Yes, It’s Still Technical:

Okay, so the elephant in the room is: work can still be very technical and confusing. And that is why it is essential to show people what you’re doing. Some work requires typing many lines of code; some requires pointing and clicking. A video editor for a major motion picture isn’t necessarily less technical because they don’t write lines of code. And we know someone in the world is buried deep into a matrix of C++ code on some major project.

By putting together the big picture and the details, you can get a complete picture of what is being done.

This is the Conclusion, Technically:

So, the next time someone tells you that an interface isn’t working, try to resist the temptation to say, ‘you’re speaking too technical.’ Instead, hear them out, and ask them to show a real example as they explain if they can. Ask them to show the flow and the expected results.

By embracing technicality and seeking to understand the technical details and capabilities of the systems and processes we rely on, we can better navigate and make sense of the complex world of technology.

And then maybe developers can get as much technical respect as the people dreaded for giving you a root canal…

Maybe.

--

--

Olly Akanni
Technical Writing is Easy

Army Major who likes Analytics, JavaScript, and Coffee... oh and I write sometimes too.