10 Invaluable Tips for Successful Tech Articles

Featured on Hashnode

Subscribe to my newsletter and never miss my upcoming articles

I'm a developer learning to write technical articles. This is my journey.

1. Go straight to the point

Don't start with an introduction. People's attention is too scarce.

Move introduction to the bottom where people are already attracted by your article.

An invitation to keep reading and a FOMO call.

Example

See this article tagline. Many writing platforms include taglines along with the heading as a preview. It is also very important for SEO.

Tip: check your title case.


2. Write for yourself

Write about things you care. You can always check for hot topics and article requests. My personal advice is:

Write about something that you are passionate about.

Example

Engage in discussions about something that moves you. You can do it on Twitter, Discord, Forums, etc.

Tip: Ask for opinions and write an article on the discussion.


3. Write for research

Writing is a great opportunity for research. You need to learn and master a topic to teach others.

Example

I wrote this article because I came across the concept of Zombies and got excited about it. Read a lot and wrote my own examples.

Tip: Have a ToDo lists of things you wish to learn.


4. Write in plain English

English is not my first language. I wrote my first articles using presumptuous words (like this one).

Then I came across plain English.

Made some free courses and learned the basic rules.

Example

The form must be completed by the applicant and received by the financial office by August 1st.

This uses a passive voice and it is ambiguous.

We must receive your form by August 1st.

Straight to the point.

Tip: Use online checkers (described below).


5. Picture and headline are the only stuff 100% users read.

Choose an attractive (but never misleading) title. Use provocative but conceptual pictures.

Example

There are lots of free to use pictures on Unsplash, Pexels, Pixabay, Stockvault and more sites. Don't forget to add a courtesy backlink like this one:

Photo by Artem Maltsev on Unsplash

Tip: Search for allegorical and abstract images.


6. Play especial atention to, Spellimg, gramma And capitalisation.

This is important if you are a non-English speaker. Did you notice the above title?

We don't read as we speak.

We must omit passive voice, avoid forceful words, etc.

Example

Use Language tool, Grammarly or similar and Hemingway Editor for improvement.

Tip: Translate the sentence to your language back and forth.


7. Be consistent

Try to develop a personal style and stay loyal to it. People will recognize it as your fingerprint.

Example

I write one article a day with the same template format.

Tip: Have a template in markdown.


8. Use code examples

Humans learn by examples. Tu support your story or thesis a clarifying example helps a lot.

Embed code in gist. So you can update it if someone points an error and you can also run it and debug it there.

Also, it is easy for your readers to copy and paste it.

Example

The Code Smell series has examples in many languages which I don't master. This is also related to tip 3)

Tip: Have the code under version control.


9. Cross-reference your articles

To keep articles small you should link subtopics to new articles. This will work as a zooming concept reading list.

Example

This whole article is a cross posting example. It has many hyperlinks for related concepts and details.

Tip: Cross post from popular articles to strategic ones.


10. Read and Follow the Right People

Writing tech articles is a meta activity.

Besides your domain expertise (I follow software crafters), you also need to follow tech writing experts.

Example

Find your favorite writing authors like Victoria Lo, Sai Laasya Vabilisetty, Tapas Adhikary, Amarachi Emmanuela Azubuike or Catalin Pit.

Follow blogging topics like technical writing, blogging, writing developer-blogging, etc.

Tip: Follow them!


Conclusion

I always wrap up my articles with a short paragraph.

These tips are the beginning of my personal quest.

Hopefully more tips will come very soon and will add new articles to the series

Murewa Ashiru's photo

Great content. Thanks for sharing

Mohd Shad Mirza's photo

Such a great read Maxi Contieri
Thanks for sharing.

Mario Cervera's photo

Great article Maxi!

I specially liked the point about the code examples. It reminded me of testing 😁

Tommi Urtti's photo

"Picture and headline are the only stuff 100% users read."

Abhiprojectz's photo

You forgot to add one - @abhiprojectz

Victoria Lo's photo

Awesome one! Thanks for the mention too! :)

Amarachi Emmanuela Azubuike's photo

Great article indeed with very helpful tips. Thanks for mention too ❤

Catalin Pit's photo

Super nice article, Max! Also thank you for the mention!

Sai Laasya Vabilisetty's photo

All points are perfectly written!! Keep writing😊

Thanks for the mention it means a lot!

Tapas Adhikary's photo

Maxi Contieri, Very crisp and to the point. Thanks for sharing and mentioning among awesome writers.

Ricardo Luz's photo

Amazing article to bookmark! 😊 One cool thing that helped to start writing was the need of master in some content, when I write I am too worried about don't write wrong things so I fell obligated to do as much research as possible.

Paddy McCarthy's photo

Abstract? It's nice to first read about what the guts of the article is about.

Maxi Contieri's photo

Hi Paddy McCarthy!

I'm not pretty certain about your point.

You mean I missed the 'abstract' section?

If this is the question is the first line.

I'm a developer learning to write technical articles. This is my journey.

It is a technical article. I published some scientific papers, so I might be biased of the 'abstract' meaning (which this article lacks on purpose).

I'm open to suggestions.

Paddy McCarthy's photo

It seems you have an Abstract. Maybe that should be point zero; inserted before your current first point? Maxi Contieri