Chris Bongers

Posted on Jul 21, 2022 • Originally published at daily-dev-tips.com

The roadmap to technical writing

#writing #watercooler #beginners

I recently joined a Twitter space hosted by Emy around technical writing.
At one stage, a question about sharing a roadmap to technical writing popped up.

Listen to the recording

I thought I'd take this opportunity to write more in-depth about how I see this.

First of all, I don't like roadmaps. They are impersonal, don't add value, and might confuse you.

If we go one layer deeper, it's really around people wanting to get into technical writing, but they don't know where to start.

So let's see this as a guidance article rather than a roadmap, shall we?

Answer the why

To help you go into technical writing, you should first answer the following question:

Why do you want to become a technical writer?

The answer to that question will help you determine what to focus on and how to proceed.

Let's look at some common answers:

I don't know, but I saw everyone else does it

If this was your answer, you should know it's ok not to become one! Being a technical writer is not required when you are a developer.
You should only proceed with technical writing if you enjoy it.

I want to improve my writing

It can be that you want to improve your technical writing/writing. Again, this could have multiple use-cases, but if that's the case, you should focus on reaching a lot of people and actively look for feedback on how to improve your articles.

I want to understand technologies better

This was my primary approach. I work mainly with React in my day-to-day job, but I still have an enormous passion for exploring other technologies. My blogging allows me to research and write about these different technologies.
The main focus here should be to have fun creating projects and finding your tone of voice to explain things in your way.

I want to earn money with it

Yes, you can earn money with technical writing, and if this is your focus, you should look into finding publications that pay you to write for them.
You should focus on writing highly engaging content and explaining topics so everyone will understand.

I want people to see I can explain complex topics

For some people, their technical writing can be a valuable asset in their online portfolio.
You might want to use your articles to show that you can explain complex topics in a way that resonates with people.
If this is you, focus on writing in-depth quality articles that blow people away.

On to the how

Once you determined why you want to become a technical writer, it's essential to look at how you can become one.

And this might come as a surprise to you:

You need to write!

Write everything you learn, even if it's only for yourself. You might want to use that information later to convert it into public articles.

This is by far the easiest way to start technical writing. Explain topics that you already solved in a way that can help other people solve the same issue later on.

The pro to this approach is that it worked for you, so you already have one reader.
You, as the reader, can then evaluate if you would have used this article when needed.

Remember, technical writing doesn't necessarily mean that you have to publish your articles to the public.
There is nothing wrong with keeping them internally to yourself or a company behind closed doors.

Writing the article

Let's look at some tips to help you get your first article done.

You should already have a topic in your mind by now. If not, use the approach described above to find one.

Start by writing the title down, then decide to outline the headings you'll need to write that article.

Once you have the headings, you are 50% done. The hard work is done. Go and enjoy your coffee/tea or water 🙏.

Come back with renewed energy and start filling in the paragraphs between the headings.
It should be clear what you need to write for each section, and even when you're stuck, try re-think what you would like to read in this section.

Polishing the article

Once the article is done, it might not be perfect.
There might be spelling mistakes. It might not flow neatly.

Let's start with the easy ones to fix.

Run your article through Grammarly and Hemingway. These are great apps to help you improve the grammar mistakes in the article.

Once that is done, open the end product in your local reader and read it yourself.

Does it flow nicely?
Do your points make sense?
Should you add some images to make it more appealing?

If you struggle with these questions, you can even ask some of your friends to proofread them for you.
(Make sure they know the technical terms)

Refactor some of the main points, but don't aim for perfection.
You will also be able to find mistakes in your article. Thus perfect articles don't exist.

Instead, make sure you are 90% sure it's a solid piece and publish it!
Even if people give you advice, take that advice and implement it.

Remember: it's not a tweet. You can edit your article and improve it for future readers.

Where to publish

However, most of you will likely be public writers, which is excellent.

So once you decide you want to publish your article, it comes down to determining how and where you will post it.

The main trap for developers is to build an over-the-top engineered solution for publishing some simple text-based article.

Yes sound crazy, right, yet everyone does it 🤦‍♂️.

Instead, focus on writing. The end goal of your articles is to provide content to an end-user.
They don't care how your website looks.
Rather how good your content is, and most importantly, if it solves their problem!

So instead of building your blogging platform from scratch, pick something already made.

Some picks:

It really doesn't matter much, but depending on your goals, your audience might be different, so do look at what kind of people you are looking to reach and if the chosen platform makes sense.

Once you have picked one of the options, go ahead and publish that article!
Don't be afraid it sucks, and let everyone know you wrote your first article.

The tech community welcomes new writers; most will be happy to read your article and let you know their thoughts.

Of course, there can be feedback. You should embrace that with both hands and consider why someone gave that feedback.

Did you not explain something clearly?
Did you make a technical mistake?
Did you forget a prerequisite?

Whatever the reason is, adjust your article where you see fit and take that learning to the next one.

Conclusion

There is no straightforward roadmap to becoming a technical writer.

You should focus on solving the primary purpose of your article and write your first article.
Learn from your mistakes, write some more, and keep on repeating.

Also, don't get sucked into creating a platform, as there are many great platforms already out there.

Last but not least: Have fun writing!

Some more information in The secret to my writing process