5 Big Mistakes I Made Writing Technical Articles

5 Big Mistakes I Made Writing Technical Articles

... and how to avoid them.

Featured on Hashnode

TL;DR: Read your articles on a mobile device.

Today Davide Bellone mentioned one of my articles on Twitter.

I frequently read my articles again and make small adjustments.

To my surprise, The AMP version of my article was impossible to read.

Headers

Bad headers usage

Embedded Non-Canonical URLs and YouTube Articles

Non-Canonical Urls

Missing Code Samples

Missing code samples

We cannot Read Code on a Device

Code is not embeded

It is a pity. I do a lot of research on my articles, and they look like a mess.

The Solutions

Let's find and correct the 5 more important problems.

1 - Preview the article in AMP Mode

This is the original article:

1 - You can preview any web page on all major browsers like Chrome, Firefox, Safari, or Edge.

2 - Fetch your amp equivalent page with Google's tool.

3 - If the site supports amp as an alternate browser (like Hashnode does) you can open it even on your desktop and play around with your drafts.

Desktop Version

AMP Version

2 - Embed the code

I use gists in all my articles because I can run them in an IDE and I sometimes change the examples. Gist is also very good for cross-posting since it keeps all articles synchronized.

Readability is a must. From now on I will update all my articles embedding the code as plain text.

I will keep gist for control version, but not for embedding.

Try reading this:

against this:

movie.rate.warnIfNotAllowed(this.age);

Which is better?

I Use markdown comments to keep track of the code

[//]: # (https://gist.github.com/mcsee/ab050467c32205a1b8623352f6bb8dd8)

3 - Use Alt Text whenever possible

This is a YouTube embed

and this is what you see on an AMP page:

youtube.com/watch?v=z43bmaMwagI

a much better link would be

If considered harmful: How to eradicate 95% of all your bugs in one simple step - Jules May

Readers might even save the video for later watching if the title is interesting enough.

4 - Pay Special Attention to Images

Images drive a lot of traffic to your site. Even if you use them in a metaphorical way.

If you use Google Search Console you can try adding a filter:

"Search Type: Image"

If you add Alt description to all your images you will bring searches to your articles both from the content AND from the image descriptions you choose!

Remember to describe the image's intent, not what the actual image does.

Advantages and Disadvantage of using the Singleton Pattern

Bad

![drawisland.png](https://cdn.hashnode.com/res/hashnode/image/upload/v1620862898080/t0bfYGzmz.png)
![Singleton.jpg](https://cdn.hashnode.com/res/hashnode/image/upload/v1620862898080/t0bfYGzmz.png)

Good

![Advantages and Disadvantage of using the Singleton Pattern](https://cdn.hashnode.com/res/hashnode/image/upload/v1620862898080/t0bfYGzmz.png)

The article referenced all hashnode posts I wrote before customizing my domain.

So I replaced links like:

https://mcsee.hashnode.dev/coupling-the-one-and-only-software-design-problem

with my vanity ones:

https://maximilianocontieri.com/coupling-the-one-and-only-software-design-problem

They are better for SEO and personal branding.

Bonus

As always, remember to check your articles with Grammarly and HemmingwayApp.

To wrap up

After applying all these recipes to the original article we can see it is much easier to read!

This amp version is better

This amp version shows embedded code