What People Get Wrong When They Write About Technical Stuff

The Internet is full of writing about technical topics, and as a writer for the Internet, you probably have an opinion about what works and what doesn’t. But it’s not always obvious how to apply these opinions to your work. 

I mean, sure, you know that “tl;dr” is annoying and no one wants to see blockquotes that are yellow on black text with no explanation of what any of the terms mean (that’s called an “obfuscated quote”). 

But when it comes down to making your content clearer and more importantly, more concise it can be hard to tell whether you’re helping or hurting your readership. 

So while we can’t give a simple formula for writing good technical content here at Buzzword Bingo HQ because we haven’t found one yet ourselves (though if anyone has suggestions send them along!), at least we can share some things that most writers do wrong when they try their hand at explaining something technical:

How to Build Your Career as a Technical Writer – YouTube
1. Understand the Field: Gain a clear understanding of technical writing’s significance and impact in various industries.
2. Develop Essential Skills: Hone your writing, communication, and research skills to effectively convey complex technical concepts.
3. Education and Training: Consider pursuing relevant educational programs or courses to enhance your technical writing expertise.
4. Create a Strong Portfolio: Build a diverse portfolio with sample pieces, freelance projects, and collaborations to showcase your abilities.
5. Industry Knowledge: Familiarize yourself with different industries and their technical requirements to broaden your career prospects.
6. Networking: Connect with professionals in the technical writing field to gain insights, advice, and potential job opportunities.
7. Continuous Learning: Stay updated with evolving technologies and trends to stay relevant and adaptable in the field.
8. Adapt to Change: Embrace changes and challenges as opportunities for growth and development in your technical writing journey.
9. Balance and Enjoyment: Strive for a healthy work-life balance and find joy in the process of creating clear and impactful technical content.

Not Everyone Is Going To Read This

Most people will not read the whole article.

The more you think about the audience you’re writing for, the more it’ll become clear that they aren’t like you at all.

Some of the audience are not like others.

If you want to be a great writer, one of the most important things is to realize that not everyone is going to read what you write. A lot of people who are interested in your topic aren’t going to read your blog post or article and that’s OK!

The first step in writing with an audience in mind is figuring out who your audience is, and what they might be interested in reading. Once you have this information, it will help guide your writing style and format choices (long form vs short form) as well as what kind of content and topics would be valuable for them.

Building a successful technical writing career requires a clear understanding of the field and its significance. Learn more about What Technical Writing Is and Why You Should Care to pave your way towards a fulfilling profession.

Your Audience Has Limits

Your audience is not a computer.

Your audience is not an alien, even if you are writing about aliens.

Your audience is not a machine it’s made up of human beings who have limitations and needs that must be respected, including the need to understand what you’re talking about.

Most People Don’t Know Your Jargon

You know your jargon, but not everyone does. Don’t assume that everyone knows what you mean by “algorithm” or “covariance matrix.” If there’s a word or phrase that would make your writing clearer and more accessible to your reader, don’t use it just because it’s part of the technical lexicon. It’s not that hard to explain these terms in plain language:

Algorithm: A Series Of Steps Used To Perform A Task (E.G., Turn On The Lights)

Covariance matrix: A way of describing how things relate to each other (e.g., how much one person likes another person)

Are you aspiring to become a skilled technical writer? Check out our guide on How to Become a Technical Writer – Earn Six Figures in the Next 12 Months to discover actionable steps to achieve your career goals.

People Read Tofu, Not Mofu

TOFU is the beginning of a piece of writing. It stands for “Tell, Old Friend,” or “Tell, Openly Friendly User.” This part of your writing is the first three to five sentences that you have written about a subject. The MOFU is what comes next it stands for “Middle OFU.” 

The MOFU is where you say something about your TOFU in more detail or from another angle or with more examples and data points.

If you’re like most people who write longer pieces (like blog posts), then chances are good that you had a pretty good idea of what was in those first few sentences when you sat down at the keyboard on Thursday afternoon after lunch (just before Happy Hour). And if not? Well… then maybe this post isn’t going to help much!

If You Want Readers To Remember, Let Them Do The Work

The next step is to write about how the reader can do this. When you’re writing, remember that your audience’s ability to understand you comes from their ability to relate what they are learning with something they already know.

So what do we need to know? To make a comparison, let’s say you wanted to write about how walking helps us lose weight. You should explain the problem: “Being overweight is bad for our health.” 

Then you should give an example of how walking can help: “You burn calories when your muscles contract.” Next, give a few more examples of things people might not realize would help with weight loss: “Walking makes your body work harder than if you were sitting still,” or “Walking improves circulation” (both these are true). 

Finally, explain why it matters and why it’s useful: “By walking regularly and getting more exercise in general, which will result in greater calorie-burning activity throughout the day.”

You Are Not Wikipedia. Reference Wikipedia

When you write about technology, don’t try to be Wikipedia. Instead of looking for places where your article can link to Wikipedia, look for places where it can link to your research, writing, thinking, and expertise.

When I was in college, one of my professors told me that the best way to learn a new concept is by teaching it. The more effort you put into explaining something complex in simple terms, the better you understand it yourself, and the easier it will be for others to follow along with what you’re saying as well.

Writing is not easy; there’s no replacement for hard work when it comes time to sit down at a keyboard and type up an article or book chapter. 

But if we all make this small effort each time we publish something online (or even just share a quick thought on Twitter), we’ll all benefit from having access to higher quality content than ever before and hopefully help save ourselves some time as well!

A successful career in real estate writing demands specific strategies. Explore the 10 Secrets to Succeed as a Real Estate Writer for valuable insights that can help you excel in this competitive industry.

Don’t Assume Your Readers Are Losers For Not Knowing Something You Take For Granted

You will have to adapt to your readers. People are busy, and they don’t want to read a long explanation of the difference between TCP and UDP. If you want them to understand something important, you need to make it short, clear, and compelling even if that means leaving out some details.

But don’t assume your readers are losers for not knowing something you take for granted. They’re not; they just haven’t had time or reason yet!

The show, Don’t Tell

You can’t just tell your readers that They need to do something. You have to show them how to do it.

Let’s take a look at an example from the source code of this blog post. The author says, “If you’re going to write about technical topics, you should try and make your writing accessible to as many people as possible.” 

Well, we could take this sentence and replace “accessible” with another word that means essentially the same thing: readable, understandable, or comprehensible. Then we’d be left with something like this: “If you’re going to write about technical topics, try making your writing readable.” 

But that still doesn’t explain what makes good writing accessible for non-technical people (or whatever). Instead of just telling us what makes good writing accessible to other people which is not enough information on its own the author describes the problem they had while trying to figure out how exactly they should go about making their own.

writing is more approachable in general terms by giving examples from different types of media such as books vs blogs vs instructional videos etcetera.

Explain Only What You Have To Explain No Less, No More.

The first and most important rule of good technical writing: Explain only what you have to explain no less, no more.

That sounds like it could be a lot more complicated than it is, so let’s break it down into two parts. 

First, if you’re explaining something technical to a non-technical audience, don’t explain something that’s already been explained in the article or video (in other words, “don’t repeat yourself”). 

Second, if there’s an obvious way for someone to understand the thing you’re explaining (for example, if you already explained how some sort of device works), then don’t explain that part again either let your reader use their intuition!

When you explain something technical, actually explain it, don’t just describe it or mention it in passing.

You Need To Explain What It Is, How It Works, And Why It’s Useful

This sounds simple and obvious but most tech writing gets this wrong in one of two ways: either they describe the thing as though it were an alien artifact that has just been discovered on Mars (“It looks like a piece of metal with wires coming out of it. 

It has a plug that goes into another device. Its purpose appears to be unknown at this time we will continue our investigation”), or they only mention the technical aspect briefly then get straight back into describing how cool the product is or how much money you can save by using it (“This cable allows you to transfer data over long distances at super-fast speeds!”).

Crafting compelling real estate copy is essential to engage your audience effectively. Enhance your skills with these 15 Ways to Improve Your Real Estate Copywriting techniques and watch your writing resonate with readers.

Your Job As A Writer Is To Solve Problems, But Be Aware That You Might Be Creating Your Own

If you’re writing about technical topics, your job as a writer is to solve problems—not create them.

The problem that people often get wrong when they write about technical stuff is that they assume their readers will understand what they know. 

They don’t realize that the audience might not know what they know, so they just assume that the reader has all of this information already. And while this may be true for some readers (like programmers) it’s certainly not true for everyone else!

If you write a book on programming languages and assume everyone knows how to program, then who are you writing for? If your book doesn’t explain basic programming concepts like variables or functions, then who will read it? The short answer: nobody!

Every technical writer needs the right tools to excel in their profession. Discover the top tools that can streamline your work in our article on Top 16 Most Useful Easy-to-Use Technical Writing Tools, ensuring your documents are accurate, organized, and professional.


If you do decide to write about technical stuff, the most important thing is to remember that your job is to solve problems and that means making sure your readers can understand what they’re reading. This means not just explaining things clearly but also giving them context and showing how they fit into the world around us. 

Otherwise, you run the risk of confusing people and leaving them feeling lost or frustrated when they try to get something useful from your content!

Further Reading

If you’re interested in further exploring the field of technical writing and enhancing your career, consider these resources:

How to Become a Technical Writer: Discover the essential steps and skills needed to embark on a successful technical writing career.

Technical Writer Career Guide: Dive deep into the role of a technical writer, from required skills to industry insights, in this comprehensive guide.

Becoming a Technical Writer: A Comprehensive Guide: Learn about the different paths to becoming a technical writer and gain valuable tips for excelling in this profession.


How can I start a career as a technical writer?

Starting a career as a technical writer involves acquiring a strong grasp of writing principles and the ability to communicate complex information. You can begin by improving your writing skills, gaining familiarity with technical subjects, and exploring various resources available online and through educational institutions.

What skills are essential for a successful technical writer?

A successful technical writer should possess strong writing and communication skills, along with the ability to understand and explain complex technical concepts in a clear and concise manner. Attention to detail, research skills, and the ability to collaborate with subject matter experts are also crucial for effective technical writing.

Do I need a specific educational background to become a technical writer?

While a specific educational background is not always mandatory, many technical writers have degrees in fields such as English, communications, or a related technical discipline. However, practical experience, a strong portfolio, and a willingness to learn and adapt can also open doors to a successful career in technical writing.

How can I build a portfolio as a novice technical writer?

To build a portfolio as a novice technical writer, consider taking on freelance projects, contributing to open-source documentation, or creating sample pieces that showcase your ability to explain technical concepts. You can also collaborate on personal projects or participate in workshops and writing groups to gain valuable experience.

What industries hire technical writers?

Technical writers are in demand across various industries, including technology, healthcare, finance, manufacturing, and more. They play a crucial role in creating user manuals, guides, documentation, and other materials that help users understand complex products, services, and processes.