I have read hundreds, if not thousands, of technical articles, and I have seen the same mistakes recurring. Thus, in this article, I want to point them out and tell you how to fix them.

The most common mistakes technical writers make:

No article structure
Using images of code snippets
Trying to meet a word count
No application demo
Long sentences
No alt text and image SEO

Let's proceed further by taking each point individually.

No article structure

One of the biggest mistakes is not having a structure for the article. The articles have no sections, headings or even paragraphs. It just goes on and on, which makes it very difficult and tiring to read it.

Even if it has paragraphs, some of them are so long you lose the will to read them. This mistake can be fixed by:

splitting your article into sections
using headings to differentiate sections
split long paragraphs into multiple paragraphs

Using images of code snippets

One thing I observed a lot in technical articles is using screenshots of code snippets. Some people include screenshots of code snippets because they look nicer than code snippets. However, it is not the best idea to do so.

By using images of code snippets without alt text, you exclude blind and visually impaired people. And the vast majority of screenshots do not have alt text.

Moreover, it's frustrating for everyone if they want to quickly try out the code. Let's say someone wants to try a feature from your tutorial quickly. Or, the code written by the reader gives an error, and that reader wants to copy > paste your code to compare the two code snippets. They cannot do that.

Overall, including code snippets in technical articles is not a good idea. Use code snippets or Gists in your articles. Although, if you are stubborn and want to use screenshots, add alt text.

Trying to meet a word count

When I started with technical writing, I tried to make all my blog articles 2000 words long. After all, that is what I have seen online - that long articles are better! However, there is no need to make an article long just for the sake of having X amount of words.

If you can write a technical article in 500 words, why would you want to make it longer? People want to learn new concepts or solve their problems as quickly as possible. Focus on solving a problem or teaching a concept, not meeting a word quota.

However, that is not to say you should not write long articles. The point is not to add fluff to make the article longer if you can solve a problem or teach a concept in a short article.

With that being said, do not worry about the length of the article. Focus on providing value.

Not having a demo of the application

Many technical articles teaching how to build an application do not include a demo of the application. If you write a tutorial about creating an application, it would be nice to attach a Git repository. Or something similar, where people can access the code.

It's a bonus if you add a demo application where people can see it in action. However, at the minimum, I advise adding the complete code of the application.

Long sentences

Long sentences are difficult and tiring to read, and it put people off from reading them, and this sentence is an example that makes me curious if you read the sentence up to this point.

Did you read the whole sentence from above? Imagine the majority of the sentences from a technical article are that way. Would you follow such a tutorial?

Thus, split long sentences into multiple sentences, and try to keep one idea per sentence. Don't write sentences that occupy two paragraphs. They are complex and confusing to read.

Keep it short and to the point.

No alt text on images

Many articles include images without alt text. Now you might ask why that is important since we can already see what's in the image. However, that is not the case for blind and visually impaired people. They rely on alt text to understand what the image shows. Thus, it's super important to add an image description if you do not want to exclude people.

Moreover, alt text is vital for SEO. When people search for stuff online, your images are shown in the search results if they are relevant. Thus, they can bring traffic to your blog. Here are the three top suggestions when using images in articles:

Use a descriptive name - rather than having a picture named my_image21gdy732.png, name it accordingly. For instance, if your picture shows your VS Code editor, you can use a name such as visual-studio-code-editor-screenshot.png.
Add alt text - use the alt text to describe what the picture illustrates. Using the same example with the VS Code editor, you could use something such as This is an image of my Visual Studio Code editor setup.
Use semantic HTML - this may seem like basic advice, but you have no idea how many people misuse HTML.

With that being said, by adding alt text and implementing basic SEO tips, you make your blog more inclusive. Moreover, it can boost your blog in search engines.

How to fix them

Now, it is time to fix these issues and improve your technical articles.

Structure your articles into sections. Use headings to differentiate the sections and split big paragraphs into multiple paragraphs.
Use text code snippets or Gists instead of screenshots of code snippets.
Don't focus on meeting a word quota. Focus on teaching a concept or solving a problem. In layman terms, focus on providing value.
Add the complete code of the application so people can play with it.
Split long sentences into multiple sentences to make the article flow better.
Add alt text to your images. Moreover, use a descriptive name for the picture and use semantic HTML.

Before closing off, I recommend the technical writing courses from Google. It's a great course!