"Just install Istio..."
"The customer always presses the ‘Submit’ button..."
"You only need to set up Kubernetes correctly..."
"Someone should fix this bug..."
Have you heard sentences like these before? As a consultant and software architect I keep hearing these or similar phrases. And each time this triggers my attention and curiosity.
Let me try to explain why these phrases are problematic and how I try to deal with them. And before I get angry mails, I mean no disrespect to the authors, when I quote some text. I use examples to drive home my points.
Don’t condescend to the audience
Most of us read manuals, tutorials, books, and articles as part of their daily business.
Here are some examples.
"With this operator you just have to create and deploy a simple Custom Resource (CR) with your desired rate limit configuration." (see https://events.istio.io/istiocon-2021/sessions/kubernetes-operator-to-manage-rate-limit-istio-configurations/)
"Using PromCat.io is the fastest way to create the dashboard, you just have to execute one command to get your dashboard with all metrics at once." (see https://sysdig.com/blog/monitor-istio/)
Both cases are well intended. Both want to suggest that following the instructions is easy. One command and you are good to go. One piece of code and ready to roll.
But is it that easy?
What if it "just" does not work on my system? Should I ask a question? Well, it should be super easy, right? So asking a question might put me up for ridicule.
I am aware that this seems like I am exaggerating. Nevertheless, using phrases like "...you just have to execute..." can be patronizing to our audience. We lose nothing by dropping that single word.
"Using PromCat.io is the fastest way to create the dashboard, execute one command to get your dashboard with all metrics at once."
Loaded terms lack accountability
Someone is no one. If we are that unspecific and general, we mean everybody and nobody at the same time.
"Someone help me". We mean everybody around us. But we have to wait until somebody actually feels addressed. Everybody could shrug this off and do something else.
"Jill, can you please help me". This is clear and direct. Jill knows what is up. She will either help, or point us to someone who will.
The same holds for decisions. "We don’t think adopting Rust is a good idea at this point". Whom should I talk to, if I disagree? Who is this "we" - only you or you and Bob or you and twenty other people?
"Wang, Bob and I don’t think adopting...." is clear and cannot be misunderstood. If I want to introduce Rust at a later time, I know who wants to join the discussion.
Being explicit leads to accountability. That is why we assign tickets to specific engineers. There is no option to assign a ticket to "somebody".
Loaded terms hide details
"Deployment — describes the desired state and makes sure to change the actual state to the desired state if needed. A deployment manages Pods and ReplicaSets so you don’t have to. Just like magic!" (see https://blog.sourcerer.io/a-kubernetes-quick-start-for-people-who-know-just-enough-about-docker-to-get-by-71c5933b4633)
"Just like magic". Is it though? Or is it well designed and are the underlying details omitted for brevity. Using terms like "magic" deters readers from understanding what is going on. A learning opportunity lost. A better approach can be to add a link to additional documentation: "Read the instructions at https://someaddress/foo.html if you want to dig deeper". We do not patronize the audience. They can decide for themselves.
"Obviously, the service needs to call the authentication service to get a valid token"
"Obviously" is a similar case. If something is obvious, then why mention it. Or is it only obvious to us, and the audience is not smart enough? Again, condescending.
We lose nothing by dropping that term. "The service needs to call the authentication service to get a valid token". It may be obvious or not. Who are we to say?
A final example is "always".
"The customer always authenticates using the mobile device."
Really always? There is truth in the saying that the exception confirms the rule.
If we use "always", we block the road to thinking about exceptions. We simplify reality. What about customers without a mobile device? Are they excluded? Why? Questions we cannot ask if "always" was always true.
Loaded terms are a unspoken invitation for dialog
Although I am triggered by loaded terms, not all is bad. Whenever someone uses terms like "just" or "obviously", I try to use them as a doorway to additional conversation. Most people do not intend to be condescending to their audience. So, if I notice someone using loaded terms I start asking questions.
"Just enter a single command and the system is up". Ok, but what if that command fails? What should I do?
"We need to set up the Kubernetes cluster by tomorrow". Ok, who takes care of this? Is it Jill or Bob?
"The users are always onboarded using a Jira workflow". Ok, but what if Jira is down? Is onboarding stopped then? Or is there a secondary workflow?
Communication is key. So, let’s take these loaded terms as an invitation.
Summary
This very short text is me venting. I do not want to exaggerate the impact of loaded terms. But our texts and our conversations will improve if we avoid them. The audience will be more engaged and invited to join the discussion.
Keep in mind: Obviously, we only need to just drop loaded terms to always write better texts :D
What are your loaded terms - how do you handle them? Let me know. I am curious about your experiences.
Top comments (0)