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.
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 something that you are passionate about.
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.
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.
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.
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.
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.
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.
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.
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.
Tip: Follow them!
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