Writing proper technical articles

Since I moved from static pages to a more dynamic website for my blog, I had the chance to get back and read most of the posts I had written during my career development. I must say, blogging helped me so much with making a very good impression among other developers, recruiters, and managers. People appreciate my contribution to the Android/Kotlin community no matter how advanced or simple the use cases I treated were.

However, now that I have more experience in writing posts, I was able to spot some crucial mistakes on my journey with my blog on the side. I will write some of them and some advice, so the others who might want to start a technical blog too can keep them in their minds.

๐ŸŸข The goal

Do you want to be famous? Recognized? Wrong industry. There are so many amazing developers out there that can bring your hundred-lined solution and long explanation redundant, with just a line of code.

Do you want to help others? Good. But how? By becoming an influencer about the platform, or finding a problem and providing a solution for it? These and other similar questions will help you understand the why for creating a technical blog post. One mistake I made about the goal was falling into the trap of the platform influencer. I was hyped and excited about new APIs or technologies because Google was telling me to be so. Such a terrible mistake.

I don’t want to be misunderstood here. Trying a new tool, new libraries, and APIs is never a bad idea, and neither is blogging about your experience. But being hyped about shiny new tools that will get deprecated in two years (along with the technical blog)?! That’s a red flag.

Always try to provide a value, do not fake the value.

๐Ÿ”ด Don’t jump too early

I had a couple of people that I used to follow and read the content they produce. Really good engineers that were also blogging their favorite topics and experiences. There is nothing wrong with wanting to be like them. But there is something wrong with wanting to start a technical blog because they also had one. The experience the others might have had was ahead compared to mine (I started my technical blog when I only had 1.5 years in Android and something like a year more in tech). Again, trying to treat advanced topics with such a small experience would take you as a writer to misguide all the other new readers and developers who clicked your article to find a solution.

๐ŸŸข Find the accurate example

I knew how to use most of the tools that I wrote about. However, I had an issue with finding good examples for readers to understand. I wrote an article named “Kotlin, beyond nullability”. What I treated in the article though, wasย Kotlin scoped functions. What I meant by beyond nullability was something like “let’s try some more stuff except Kotlin vs Java on nullability”. Furthermore, the examples about when to use an also, a let, an apply were terrible. I guess this comes back to the experience issue.

๐ŸŸข Mind your English

Before submitting an article, have it checked with some language tooling for typos, sentence structure, or wording. It’s uncomfortable reading articles in terrible English.

๐ŸŸข Make your point clear

Sometimes you would assume readers understand what is in your mind, but if it doesn’t get articulated in black and white it would bring to more confusion than solving their problem.

๐ŸŸข Get feedback

Post your article on forums like Reddit, where other professionals are. They can tell you what is wrong with what you might have written. If they do not provide an alternative solution or a better one, ask for it yourself. Also, check if people add stuff to your article through a comment. If you like the solution include their point in the post and give them credit for this. This would also strengthen your network.

๐ŸŸข Write follow-up articles

If you feel like you messed up, the feedback you got hit you hard, and now you feel terrible, but you now know the solution, I would recommend to write a follow-up article rather than just deleting the first one. On the second one, explain what is wrong with the first one and provide a better solution.

๐ŸŸข Understand what is going on under the hood

This is a typical programmer issue. Jumping to quick implementations, and also into writing a blog post. Intelligent people tend to underestimate almost everything. And that’s where they break their necks so hard. There is nothing more awful than writing a blog post about a new tool that you do not know how it is built internally. You don’t have to know everything in detail, but you should definitely know why something you are introducing as a super solution is introduced to you in the first place, and second, how does it work? For example, I learned about the observable pattern, after using LiveData or RXJava. That’s the worst approach. You should definitely know the what and how of the observable pattern to use such tools in the first place.

๐ŸŸข Try every example you write about

This is something I have respected and I have never neglected. But I read a lot of code in online articles, especially on Medium which is literally stolen from one article to the other, or just copy-pasted from StackOverflow. This is pure plagiarism and should never happen.

๐Ÿ”ด Do not put your feelings in technical, scientific articles

Nobody, literally nobody cares how excited you are because Google just introduced Jetpack Compose yesterday. Readers just want to see if there is some opinion that makes more sense than theirs, learn something new or unlearn something they knew. You really look like a child when putting your own emotions in a scientific blog post. This doesn’t mean you should not greet or welcome your readers, but it also doesn’t mean that your feelings go in black and white.

๐Ÿ”ด Not all the feedback makes sense

Sometimes, people ask for stuff that is not necessary. One time, a person asked me for a TLDR (too long, didn’t read.) While TLDRs is really nice to have, the article I am referring to was only five short paragraphs. That’s some level of cynicism over there. Some people are just used to learning new things on TikTok and that’s less than ten seconds. Blog posts should be well elaborated in my opinion, otherwise, go with a TikTok channel or an Instagram account.

It can happen that you cannot sum up the article in two sentences. If that is the case, just leave your article without a TLDR.

๐Ÿ”ด You don’t have to write a blog post

I’ll close up with this. If you think there is already plenty of good content, don’t waste your time. This doesn’t mean you should not write about a topic that some other developer wrote, but definitely, an article about Kotlin vs Java, Dagger vs Koin, or Flutter vs Android, would be boring for everyone to get back to.

Writing technical articles and providing actual value is hard. Bringing one topic from your mind in the paper will never be perfect. However, keeping in mind some of the above-mentioned pieces of advice would definitely help you produce good content, be helpful to others, and have a clear goal about the topics you are supposed to treat.