In honor of my talk at Indy.Code() this week I want to talk about vocabulary and communication. I was having a great conversation the other day about the phenomenon of "cookie licking".
This concept can be applied in any number of ways. From the way an application is built to the transparency of the developer doing the work. However, I think the majority of cookie licking instances are done by accident. A lot of the time, it's just that no one else is able to understand what a specific engineer is doing. So they become the only person able to do that work by default.
Oh How Quickly We Forget!
Anyone remember what it was like to start in this industry? I got lucky, I went to school for (some) of it. So I knew what an IDE was, I knew the right terms for data structures, etc. But my first day on the job was still a different world!
This list could go on and on. In so many different directions. But there was such a breadth and depth of vocabulary that existed in real life coding environments! And half the time people would talk about them and I'd be lost.
This has only grown. Just think of all the cloud service provider tools...
Vocab as Gatekeeping
The problem with this never-ending revolving door of tools and names and vocabulary is that it makes it hard for those outside our industry to understand what we're talking about.
Unfortunately, there was a time where this was done on purpose. As a result, learning tech lingo is like learning another language, even beyond the code itself. So once you know how to translate between that lingo and layman's terms you've created pretty good job security for yourself.
Instead of ranting about all the reasons we shouldn't promote this exclusive vocbaulary, I'm here to try and help! I want to focus on just a few areas you and your company can cut down on the vocabulary necessary to do your job. This will help with onboarding, it'll help with handover, and it will ultimately decrease the bottlenecks around systems.
Acronyms
I have a million amusing stories about acronyms. But the reality is that we already know this is a horrible way to communicate, yet we do it anyway! If you're writing you NEED to define acronyms the first time you use them.
If you're speaking? I'd love an example of a universally known acronym that is shortened enough from the actual term to justify its use. I'm sure there or one or two. But I'm still telling you to define it the first time you use it! And for the most part, there isn't a good enough reason to speak an acronym in place of the term it represents.
Product Names
We are TERRIBLE at naming things. Which is kind of ironic given how much we harp on computer science students to use informative variable and function names. None the less, someone somewhere decided that product names were made for marketing and not for understanding.
Well, in this field we have a LOT of those. If you're building a tool for internal use only, please don't use a "fun" name. It doesn't help anyone.
If you're building something for mass consumption? I expect the very first line on your landing page to be an explainer for what it is and what it does. And not some marketing mumbo jumbo. I'm looking at you Puppet!
Don't Know What You Don't Know
The reality is that communication in engineering is so hard and "gatekeepy" in part because we work on a lot of concepts people don't encounter in everyday life. And we need names for those things!
There is no silver bullet for this problem. But the good news is that regardless of where you are in your career, we're all actively learning. Tech moves too fast for any of us to stay in one place for too long. This is actually a major benefit!
How do you learn best? What methods of communication are most effective and the least confusing? You know the answers to these questions.
...maybe try and remember that when you're the domain expert? Being cognizant of the potential for misunderstanding is likely to slow you down and focus you enough to be more easily understood. And even better, this mindset and positioning of yourself as a fellow learner makes you approachable, prompting those around you to ask questions.
After all, we're all learning from each other!
Top comments (12)
I like that you point out Puppet as an example, because the website entirely fails to answer "What problem does this solve for me?"
It's not always marketing jargon. If I visit the Haskell website I also don't get a clear answer to that same question.
But in their defense, it might be because I'm not the target audience for either of those websites.
I hate the idea that you need to be the "target audience" though. Too often someone mentions a piece of technology in a meeting and we all go to their site to quickly understand what it does/why it's there. Every site should make the information understandable to the majority of people.
I do agree, we should try to simplify things. At the same time saying that just because you want to be included, a company should appeal to you, is wrong. I say "you" by the way as an example and with no disrespect or insult intended.
At the end of the day if a company wants to appeal to a very, very specific individual - let them. It does 2 major things.
You'll spend about 2-3min on their site and give up, saving you time and headache in the long-run with a product you would probably buy but never actually use (hello dozens of "unique and helpful" software packages).
If someone actually DOES need their service they'll almost immediately know, and their on-boarders / sales teams will be able to work with clients that they can actually help/assist.
This really focuses on platforms that are very, very B2B and not B2C (or even B2D Biz to Developer). Example being Puppet as you said. I opened their site, saw the word "DevOps" and immediately got turned off slightly. Then I read the "one liner" and realized I have no idea who they are, what they do, or if I can use them in anyway whatsoever - resulting in me closing their site. Even if my company COULD use them their marketing jargon and lack of "wtf do you do" turned me off.
I'm sure someone out there though loved the page and immediately wanted more information. =]
While that’s fair in the “it shows me I don’t want to work with them sends” I’d like us all to strive for better. But I see your point.
This is a very good perspective! I'm now trying to approach with a few tools that I know very well.
php.net has two sentences at the top explaining what it is.
mariadb.org has a very large "about" card right on the homepage.
arduino.cc also has a nice large "about" card on the homepage.
ansible.com is sort of a middle ground. it feels more like marketing jargon then actionable items.
redis.io has a nice explanation on the homepage.
sublimetext.com has quite possibly the simplest and most direct "about" one-liner at the top. fitting for what it is! plus the homepage animations are a great introduction to what the text editor is and does.
code.visualstudio.com assumes you're already looking for a code editor and know what all the buzzwords around them means.
This has frustrated me for so long, and what turned me off of AWS for so long, even though I still had to dive in at some point.
Even today I was looking at Tapad, and it took me 3-4 page clicks to figure it out, looking at their solutions and reverse engineering their copy written jargon.
Some sites I swear I'll browse every page and still not understand what they do...
I can understand the approach to appeal to, let's say, sales or non-tech oriented people using THEIR jargon, so it's not tech industry specific but probably annoying and pedantic for everyone..
Amazon are crap in naming their stuff.
I just learned (well, about a month ago) the reason some services are AWS xyz and some are Amazon xyz.
If it's used internally by Amazon and started there: it's Amazon xyz.
If it was developed as a service first: AWS xyz.
Never knew that. Interesting.
We are partnered with AWS for the last few years. Even our GM didn't know this. 😂🤣
Speaking of being bad at naming things. Every time I see "naming" mentioned, I'm reminded of a coworker in the early '90s. She named all her source files like this:
TOTO1.SAS
TOTO2.SAS
...and so on (that was MS-DOS, so filenames were uppercase).
You opened one of the files and what were the variables name?
Yup: TOTO1, TOTO2, TOTO3, and so on...
Somehow she could figure this out. But, good luck to anyone else going in there. Mind you, I started with interpreted BASIC in the early '80s and because of limited RAM we usually named variables A, B, C, D, .......
As for product names, I won't even go there.
My biggest gripe is not on a social level, but a professional level. Even switching from one toolkit to another, vocabulary changes, and not knowing the right vocabulary during an interview can prevent you from getting a job. Knowing the skills and tools isn't enough, but knowing all possible names for the tools because you never know which background the interviewer is coming from is just insane!
Thanks for reminding me of this :)