Intro
In this short post I'll share some tips to those who want to write some technical articles, but aren't sure how to do it right. Since I worked on editing a lot of technical tutorials, I understand how difficult technical writing can be. I'll do my best to explain the steps to take to write an article which will reach and help a lot of readers.
Tip No. 1 Pick the Right Topic
If you've learned something new and fun, solved an interesting challenge, or discovered a solution to a well-known problem that hasn't been documented properly, there's your topic.
Check whether the topic you have in mind has been covered before. Think about whether you can cover it from a different angle. What's the point about writing about something that people already know quite well?
Tip No. 2 Focus on the Audience
Who do you want to read your post and why? Do you want to help people who are in your shoes or might be there soon? Do you just want to share some facts you find interesting? Keep in mind that not everyone will be interested in reading about the benefits of using gRPc, learning how Kafka works, or finding out what's new in the React ecosystem.
You can start from a simple description, e.g. "This post is going to be fun and helpful to web developers familiar with working in React but who aren't experts."
Are you talking to a junior, medior, or a senior programmer? By defining the audience, you're also defining the tone of your article. If your goal is to write something for senior JavaScript developers, no need to explain what ECMAScript is, right?
Now, ask yourself, how can you make it easier for them to find your article? How would you google the solution to your problem? This brings us to ...
Tip No. 3 Choose the Proper Title
If you want to reach a lot of people, think about how they would search for the solution you're offering. Avoid titles that don't make it clear what the article is about. Try being as specific as possible - mention the technology and what you're doing with it.
For example:
❌ Don't name the article "How I Tamed a Beast and You Can Too"
✅ Go for "How to use [name of the tool] and [do something with it]", "How we [did something] by using [name of the tool]", etc. instead.
Tip No. 4 Write an Outline
Take your favourite writing tool, and draft yourself an outline. Start from the title, define subheadings, and add a sentence for each subheading.
For tech articles, having a good introduction is very important. Describe what you're going to cover and why. Make it easier for people to understand what your article is going to be about instead of forcing them to skim through it.
Subheadings are also important. There's nothing worse than reading a wall of text. Chances are that people won't even start reading the article, regardless of how well written it is, if the structure doesn't look right.
Here's a general outline that fits most tech articles
Title
Intro
Describe what the article is going to be about and list all the tools you're going to use and
Prerequisites
If you're writing a tutorial, define the concepts with which the reader needs to be familiar, the tools they should have installed, and the OS you're using if it's relevant for your topic. Working on Windows isn't the same as working on Linux.
The rest of the subheaders
Conclusion
Don't skip this part. Summarize what you've covered in the article, and ask the readers to give you feedback. You never know what you might hear. Make sure not to forget to use keywords in this section, it's SEO best practice.
Tip No. 5 Finish the First Draft
Mind you, once you're done with the writing, don't just click on that "publish" button yet. Go to sleep. Get out of the house. Read the same article tomorrow.
What looks great one day, might look like a total disaster next morning 🤦♀️ That's why this is your first draft. You need to give it a read and check the clarity of your post. In case you don't want to wait, at least send it to some of your friends to get their feedback. If you want to help people, make sure others understand what you're trying to convey.
Tip No. 6 Make the Final Draft
In this phase, you should have an article you're kind of happy with, while the rest of your friends think it's great. Don't put yourself down, and try to fix it over and over again. There's no such thing as perfection.
Tip No. 7 Add a Cover
Having even the simplest cover attracts more attention than just having a great title.
There are a lot of websites that can provide you with a free stock photo, or you can design one yourself.
Tip No. 8 Make Sure your Article Reaches Readers
You've published your article, and that's it. You're happy, and thousands of people will be thankful to you for writing it 🚀
Erm, no. 🙅♂️
Find places where your potential readers discuss stuff. Share your post on Twitter and use the right hashtags, HackerNews, Reddit, even LinkedIn. If you want people to find your post, you need to find the places where you can share it.
This is how people who curate newsletters find good articles. Here's a list of newsletters your article might end up in, wouldn't that be great?
Summary
I hope these tips helped you become more confident in your technical writing. Please do leave your appreciations and comments to let me know if this post was helpful to you 🙌
If you'd like your articles to reach more developers, apply to join Hashnode.dev blogging platform.