Avoiding the Curse of Knowledge in Your Technical Content
Sharing knowledge is easy. We can all write blogs, publish documentation, record podcasts, make videos, and create code examples. But sharing knowledge with the right audience, capturing and keeping their interest, and giving them the information they need without overwhelming or insulting them? That’s hard. That requires finesse.
Considering the curse of knowledge when examining or creating your technical content will help you keep your audience engaged throughout their journey with your product. In this article, we’ll look at some signs of the curse of knowledge in technical content, and how to break the curse.
What is the Curse of Knowledge?
I’ll take an example from one of my favorite TV shows, Breaking Bad. In the show, Walter White is a world-class chemist turned high school teacher, and he knows just about everything one could ever know about the subject. But repeatedly, his attempts to explain concepts to his students would fly way over their heads. Walter is so profoundly familiar with chemistry that it’s hard for him to distinguish what is obvious and what requires more explanation. That right there is the curse of knowledge.
Tech companies are especially prone to the curse. We’ve all seen it. Whether it’s a guide that had us opening more tabs than a detective trying to solve a mystery, an API doc that felt like we were digging for clues on each page, or code examples that led us to error messages on Google. And when it comes to marketing, have you ever seen a slew of flashy visuals and smooth jargon, but in the end, you still have no idea what the product does?
“If you’re in developer marketing, the goal is to get other developers to understand your product. And the content you create needs to bring them closer to that goal. So, the question is, while you know the why of your business, does your audience?"
Why This Matters in Your Developer-Focused Content
You might be thinking, “What does it matter? It’s more important that the content is out there and available, right?” Not quite.
If you plan your content in a vacuum, and make decisions without audience feedback and consideration, your content will be limited to your own information, assumptions, and biases – which will make it suffer and directly affect your bottom line and user experience.
For tech companies, this means your novice users may not be able to use your product properly, and your content may leave gaps where you assume your readers already know something they don’t. Instead of getting more users to fall in love with your product, you could lose your audience and your sales.
The good news is that you can avoid this curse if you remain aware of the common traps companies can fall into.
Let’s go through some ways you can recognize and avoid the common bad habits that bring out this curse. But not only that, we can go through some tips for good habits you can develop to make sure your content is helpful and valuable to your audience.
Examples of the Curse of Knowledge in Technical Content
If we want to counter the curse of knowledge, there are some common pitfalls to keep in mind when creating content of any form.
Here are six common ways the curse of knowledge tends to show up:
Being Too Close to the Product and Documentation
One common way I see this show up is with content written by the engineering or technical teams. Like documentation that might jump right into Linux terminal commands or include Python scripts without an explanation for setting up the development environment.
When the authors are deeply immersed in the tech, they can often forget that their audience may have large gaps in knowledge or basic understanding. This can result in content that is hard to follow.
Missing Beginner Content
It can be easy to skip over introductory material when gathering topics for content because internal development teams and engineers might consider them too basic for their users. But remember that everyone has to begin somewhere.
In developer marketing terms, while most of your content may sit at the 200-level and 300-level, be sure not to overlook the 100-level content that eases the beginner users into your product.
Using Jargon and Acronyms (Without Explanation)
Our day-to-day tasks and interactions with colleagues and others in the industry might be filled with acronyms that seem to be standard terminology. And sometimes, they can make their way into content out of habit. I’m certainly guilty of this on more than a few occasions.
Remember to stay vigilant and explain abbreviations and jargon as necessary, including terms that might be considered widely used.
Having a Lack of Examples
When sharing knowledge, it’s easy to fall into the trap of telling rather than showing information to the audience.
For example, if your product is a weather API service, it may be simple to provide steps to get an API key and then point them to your weather and temperature API documentation with a short code snippet and call it done. However, imagine if that same user had a concrete sample to follow that walks them through how to set up a project from scratch, securely store and use the API key, and retrieve weather data for a city. This can improve the user’s understanding, offer a solid starting point with the API, and allow them to extend it further into full-fledged apps.
Overexplaining
Being simple and concise is an art. While thoroughly explaining your concepts is helpful, the level of detail should match your audience’s knowledge level.
For beginner content, it’s useful to provide detailed explanations of simple procedures, such as how to download and install the required software. But for expert-level content, including basic instructions for common steps could lead to frustration among your readers — after all, you never want to make your audience feel like you’re “talking down” at them.
Oversimplifying
As mentioned in the previous point, your content doesn’t need to contain every single detail, just a reasonable amount. On the other hand, it also should include all of the minimal information users need to complete a task or understand a topic (otherwise, why are you even writing about it in the first place?)
If your content lacks important detail and information that leads to users having to sift through other documentation or search elsewhere for answers, they can become confused and frustrated or even give up altogether.
How Can You Lift the Curse of Knowledge in Your Technical Content?
Now that you’ve seen some ways that your content can go wrong, here are some strategies to ensure your content goes right.
Create Buyer Personas
Knowing your target audience helps you determine the right amount and type of information to include in your content.
For example, a persona for a novice developer can help you choose documentation topics to develop your content around their buyer journey.
Identify Gaps in Your Content
Do a content audit to determine where your product is missing developer content. New features will obviously leave gaps, but it can be more beneficial to know where your users are struggling so that you can address their concerns.
One way you can do this is by taking an inventory of skills or prerequisites required to complete a task or integrate a feature into an app. And then, you can check off the ones already covered by your content and fill in the remaining gaps.
Break Down Customer Tasks
Every new product has a learning curve. The onboarding process typically takes a lot of time and effort on the customer’s part. You can make your users’ lives easier by introducing them to the steps in bite-size chunks rather than overwhelming them with everything all at once.
Go through a mock-onboarding scenario and keep track of all the steps new users have to take. This will ensure you don’t miss a step accidentally (remember, just because you know your product inside and out, your new customers don’t). Some companies even start their content strategy with a series of glossary-style articles to make sure everyone is on the same page. It’s simple but effective.
Get Involved With Your Audience
One of the best ways to learn what content your customers need is to get to know them directly, especially your new users. Connect with your target audience on social media, forums, or other channels and ask them questions about their pain points and the challenges they face. Look at the support tickets and get to know the biggest issues your customers are reporting. Run usability tests and conduct surveys to gather feedback. Simply communicate and make it a two-way channel.
The better you know and understand your audience, the better you can address their needs.
Show, Don’t Just Tell
Creating relatable examples with good, clean, working code is invaluable to users. Rather than just listing steps to follow, make sure you back up your documentation with concrete examples and use cases (and perhaps even pictures, graphs, screenshots, and video tutorials).
Use Keywords
Your content should include good keywords related to the topic, especially in the title when applicable. This helps with SEO (Search Engine Optimization), which increases your content’s discoverability in online searches and allows your users to narrow in on the topic they are looking for.
It can be frustrating to get halfway through a piece of content and realize it doesn’t have what you need. Good use of keywords can help avoid this for your customers.
Establish Best Practices
If you don’t have content yet around best practices for your product, market, and industry, you really should. This is a great way to bridge the gap between new and experienced users and provide the guidance they often want and need.
Some examples of this might be advising developers on:
- Securely calling your APIs
- Avoiding rate limits
- Troubleshooting error codes
- Maximizing performance
- Properly handling events and failures
And because this is often knowledge that your engineers might have that external developers don’t, it can be an opportunity for your technical team to contribute valuable content.
Final Recommendations
It is a challenge to guide our audience through a journey of dense materials and content while making it simple and easy to understand. The curse of knowledge can leave your audience lost, and planning your content in a vacuum and making decisions without audience feedback and consideration can result in more harm than good. Your content will be limited to your own information, assumptions, and biases, leading to poor overall customer experiences.
Now that you have the tools to recognize and lift the curse, you can apply them to your content strategy and processes and ensure that your content is beneficial and your users have the resources they need.
Finally, what we’ve provided here isn’t a complete, comprehensive list of dos and don’ts but a general way to think about content pitfalls and planning.
If, after following these tips, you still feel stuck with your content, consider getting some outside eyes and a fresh perspective. While you and your team are experts on the product, a technical content team like us here at ContentLab can help ensure that you’re getting your information out in the right way, to the right people, at the right time.
