5 Big Mistakes I Made Writing Technical Articles
... and how to avoid them.
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.
Embedded Non-Canonical URLs and YouTube Articles
Missing Code Samples
We cannot Read Code on a Device
It is a pity. I do a lot of research on my articles, and they look like a mess.
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.
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:
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:
a much better link would be
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]( )
5 - Replace links with your canonical ones
The article referenced all hashnode posts I wrote before customizing my domain.
So I replaced links like:
with my vanity ones:
They are better for SEO and personal branding.
To wrap up
After applying all these recipes to the original article we can see it is much easier to read!
Great tips Maxi. Now, I'm pausing my publish a bit to take care of some from the list 😉.
Specially AMP URL to YouTube and image alt text.