Crafting high-quality content: How to write better and boost engagement
It’s simple: never say “It’s simple” (or equivalent).
I’m a big fan of Writing Well by William Zinsser. I love writing, but I’m sad because I’m not writing enough. I have plenty of drafts on various platforms, but from ‘draft’ to ‘production’ is a big step, always asking a lot of energy (if not a ChatGPT thing).
The other day, while reading a tech article, I had a feeling that something wasn't quite right. After a few seconds, I realized what was bothering me. I quickly opened the Cmd+F search function in Chrome.
- “It’s simple, …”
- “It’s easy, …”
- “Only …”
Do you see what I’m talking about? Let me give you more examples:
- “Just…”
- “Obviously…”
- “Clearly…”
- “Anyone can…”
- “It’s just a matter of…”
- “All you have to do…”
All these words make things look easy or easier. Many engineers love to write about their technical topics; it’s amazing! But they often lack empathy for their readers, the complexity of their writing, the outcome of what they are writing, and the “why” they are writing.
When you (or ChatGPT) write an article, for whom are you writing it: you or your readers?
What do we care if it’s “easy” or not?
Sometimes, we oversimplify what we write and leave out certain details because we think they're unimportant. Reading is a journey from beginning to end. If we skip parts of a book, we may miss out on crucial information that affects our overall understanding. For example, if we read pages 1-100 and 200-300, but skip over pages 100-200, we won’t completely understand the story by the end.
Simplistic statements lacking nuance and detail will lead to a lack of depth and interest for the reader. This will result in low engagement and unexpected turnover of your content (lots of acquisition but no retention).
“Making things easier” is among the most commonly used marketing phrases. Every business out there exists to make achieving something easier.
- Google? Making information easily accessible
- Instagram? Making it easy to share the world’s moments
- Snowflake? “Unlock the true value of data” (wow) easily on the Cloud
- Tesla? Making sustainable energy devices like cars more accessible
- Conduktor? Simplifying and improving collaboration of Apache Kafka
Is there a company out there intentionally making things more complicated? Perhaps there is a new business opportunity here.
When writing, we often take shortcuts to avoid explaining things that may be boring or irrelevant to the article's goal. However, we should consider what the reader wants to read instead of saying, "it's easy." Providing clear directions can help complete these seemingly "easy" tasks.
- No: “It’s time to deploy using Helm. Easy. Next we…”
- Yes: “It’s time to deploy using Helm. Check out the instructions [here]. After that, we can proceed to the next step.”
Fun Fact: “Trivial! The proof is left as an exercise for the reader”
If you've studied math before, you may have had teachers skip over solutions by saying "The proof is trivial." This has become a common phenomenon in math, to denote a situation where the instructor glosses over a complex or non-trivial proof or calculation, assuming that it is easy for the students to grasp.
A famous extreme example of such a case is Pierre de Fermat, an extremely talented French mathematician born in 1600+. He wrote “Fermat’s Last Theorem” in 1637, stating that x^n + y^n = z^n has no integer solutions for n > 2. He had a proof “that was too large to fit in the margin” of the book.
Fermat never published the full proof, which took us 350 years to solve (Andrew Wiles, 1994).
The Reader Experience: simple for you, not for your readers
When we write, we must show empathy and consideration towards our readers, considering their diverse experiences, backgrounds, and skill levels. What may seem straightforward to one person may be complicated for another.
Avoid labeling something as "easy," as this may make those who find it challenging feel excluded or inadequate. Do you want your readers to feel this way? Even if they are not your ideal audience today, they may be your audience tomorrow, so it's worth considering.
Read more about the 2 types of empathy: Cognitive and Emotional. In this article, we are really focusing on Cognitive Empathy: understand our readers perspective to improve our content.
Marketing is about Learning
Most companies create marketing content like blogs, learning courses, and tutorials. (I do the same for Kafka: https://www.conduktor.io/kafka). Yes, it’s marketing.
The purpose of marketing is to increase visibility and attract new users. Writing is crucial for achieving this, as it allows us to
- share knowledge
- generate interest
- establish a sense of continuity.
We aim to establish long-term relationships with our audience both now and in the future. Learning is an ongoing process for everyone, and we owe much of our knowledge to those who came before us. We should always be grateful for the opportunities to learn from others.
Conveying useful information and being clear and precise can have a greater impact than speaking in ambiguous terms. Effective communication is a complex art that requires practice and skill. I can tell you that because, as a founder, I know how important it is to build trust in a company: it’s not simple.
Impostor Syndrome, anyone?
Do you know what is the Impostor Syndrome? It makes people feel like they don’t belong in a field because they may find some “easy” tasks difficult. To be honest, I think in IT we all suffer from the Impostor Syndrome, as our domain is so vast and keeps growing. Do you feel it?
Writing can be compared to managing a large team (the internet!).
- A bad manager issues orders and does not build any connection with their team. This creates tension, leading to high turnover rates.
- A good manager listens to their team, guides, and supports them. This builds trust.
How to write better?
Clear instructions
Instead of using the phrase "It's easy to set up," we can provide specific instructions such as "You can set it up in three simple steps. Click here to view the instructions." Obtaining a source reference can be quick when we are familiar with the subject matter, but it may take longer when we are not.
Inclusive Language
Using inclusive language (gender neutral, no stereotyped words, etc.) to ensure everyone feels addressed and respected is also important.
- No: The foreman told his workmen to man the machines.
- Yes: The supervisor told their workers to operate the machines.
Have a Growth Mindset
The concept of growth mindset, made famous by Carol Dweck, promotes the idea that abilities can be improved with effort and perseverance. Describing something as "easy" contradicts this mindset as it suggests that things are either easy or hard without room for improvement or development.
Saying less increases Cognitive Load
It may seem counterintuitive, but articles that skip steps or lack explanations can increase the cognitive load (things you must keep in mind to understand the whole picture). Sounds odd, right? You want to say less, not to complicate things for the reader, but you are actually doing the opposite.
Why? Because the reader has to connect the dots.
This is the big difference between someone who knows (has the knowledge) and something reading disconnected pieces of information. (We talk about the Writer Curse below)
Emotional Intelligence (EI)
Capability to understand one’s emotions and use this understanding to guide thinking and behavior https://en.wikipedia.org/wiki/Emotional_intelligence
A writer with high Emotional Intelligence produces empathetic and accessible writing, in contrast to the detached perspective of a "it's easy" approach.
In the tech industry, emotional intelligence is often lacking. Talented individuals may struggle with social skills and assume everyone is on their level, making collaboration difficult.
Managers should identify what is the “EI” level of their team members to get the best out of them and understand the dynamic between them. Conflicts between coworkers will arise for sure if people are not prepared. We can correlate this to the PCK.
PCK?
I came across this new concept: Pedagogical Content Knowledge (PCK). This is about understanding how content can be effectively taught. It’s not just about knowing a subject deeply (content knowledge) but also understanding the best methods to convey it (pedagogical knowledge).
When someone writes an article saying “it’s easy,” they may have high content knowledge but low PCK. What do you think it’s the most interesting to have? Which level are you do you think?
Do you want your engineers to write about tech? Do you know if they have the right PCK?
In astronomy, Stephen Hawking, Neil deGrasse Tyson, Brian Green are well-known because they make/made complex science accessible to the general public (writing books, TV shows, social networks, podcasts, etc.). They have a high PCK while having a deep knowledge at the same time.
The Writer Curse: You know too much
Remember the Information VS Knowledge diagram above? The Curse of Knowledge or The Curse of Expertise: It’s a cognitive bias that occurs when an individual who is communicating with others fails to disregard information that is only available to themselves, assuming they all share a background and understanding.
You don’t remember what it was like not to know something.
Isn't it true that our brain works wonders by creating neuronal connections that help us understand things clearly? Our brain works quickly by taking shortcuts and avoiding the tiny details that may lead to confusion or madness. However, when we write, we may leave out important steps or explanations that would be useful for beginners or non-experts. We are too far ahead in the journey already!
You are not the user
“You are not the user” has become a ubiquitous mantra in the user experience industry to remind practitioners that their knowledge and intuitions do not always match those of the end users they are designing for.
When you work in a company, you spend your days delving deeply into your company's field. Nothing surprising here. However, the individuals who use your company product, well, they have a different occupation, another job, working in another company, correct?
This is precisely why it is crucial to converse with users to stay current on their use cases regularly, new working methods, and challenges. This allows you to create a successful product that meets their needs in the best possible manner, from why it does it to what it does and how it does it.
You suffer from the Dunning-Kruger Effect
Years ago, I read Influence: The Psychology of Persuasion (Robert B. Cialdini). I can’t recommend it enough.
This is where I read about the Dunning-Kruger Effect.
a cognitive bias for people who have little ability in, or knowledge of, a particular task or subject to overestimate their knowledge or ability in this area, while those who are highly skilled or knowledgeable may tend to underestimate theirs.
The Dunning–Kruger effect often translates to:
- Incompetent leaders incapable of recognizing their own incompetence
- Employees who have attended basic security training courses will experience the Dunning–Kruger effect. (overestimating their knowledge in this area)
The teaching journey is as important as the knowledge itself (the destination). “Better far to teach a hungry man to fish than to give him a fish already caught.”
Improving Writing Skills by Learning "How to Learn"
It’s a bit meta, but learning “How to Learn” is interesting for all the writers out there to be more efficient and gather positive feedback from their readers. This famous course is on Coursera: https://www.coursera.org/learn/learning-how-to-learn, led by Barbara Oakley (Professor of Engineering). Go, it’s free!
Conclusion
When writing anything, always re-read your piece through the eyes of your readers (probably less experienced than you on your topic).
- Ask for feedback: experts (to confirm the deep knowledge) and non-experts (to confirm the Pedagogical Knowledge).
- Your audience has diverse backgrounds, experiences, abilities, and velocity. And they are all reading to learn something.
Carefully ensure there is continuity in your writing, to keep the interest and reduce the cognitive load for your readers. This will result in higher engagement and positive feedback.
Writing is the art of translating and spreading knowledge. If you don’t make any effort to do that, what’s the point of writing then?
It sounds “simple”, right?
