Getting Started with Technical Writing

Hello dear 👋,

I'm a passionate technical writer, who writes in different platforms (including this). I also started the challenge #2Articles1Week early this year and shared it on twitter which is a means to further improve my skills, and also invite more people into technical writing.

Yes, I am also an advocate for technical writing. I've received a lot of questions on the hows of getting into technical writing from people I've tried inviting and some others who know me for what I do. I've often answered them through calls and messages, but I decided to have a general reference for everyone (from now and the future) who wants to get started with technical writing from my point of view.gra

Shall we? 😏

---

I'd start by a little introduction, state some benefits of technical writing, cover some important notes and approaches to technical writing, then I'll answer some questions I've been asked before. This article would be updated as I get newer questions.

What is technical writing? ✍

Technical writing is a form of written communication centered around a technical field. It could be documentation of a software, a tutorial on going about something or a solution to common problems.

Benefits

The following benefits are things I've personally experienced:

1. You validate existing knowledge as well as acquire new knowledge

I see technical writing as: 'You think you know lists in python? Why not try teaching it in form of writing?'

When you successfully teach it, the fact that you know lists is validated. But there's more to this. You've probably been using lists in python for a long time and now you decide to write on it. Obviously, you'd want to be very explanatory in your article, hence a question like 'Why are these even called lists?' might arise of which you do not know the answer. While making research, you'll learn what it is and add it to your article.

After everything, you'll discover you haven't just learnt what lists are, but there's extra knowledge, one of which is why they are called lists.

2. Your writing and grammar skills are improved

I recently read through some articles I wrote mid-last-year when I started writing, and I laughed at myself. I also acknowledged how much I've grown because my combinations of words at that time were poor.

The more you write, the more you learn how to write

3. Your contents speak for you and you're adding value

Writing (especially centered on a particular field) speaks for you. It speaks about your knowledge.

Also, whether you write short or long contents, you aren't only learning but adding value, especially to people reading it.

4. Job opportunities and more experience

Technical writing job opportunities to be precise. I saw a technical writing job opening last year, 2019, October, and I applied, showing them my contents. They initially stated that my contents were quite okay but I was more directed at junior developers and they expected more. They decided to give me a try, and I had to 'buckle up'. I started writing longer articles (1500 words +) while having simplicity in mind. This of course, improved my skill, and allowed me to check out complex fields in web which I was initially scared of.

Practicing is one way of improving your skill. But another is writing. You cannot write about what you do not know, except you want to deceive yourself by copying from other sources. There's this popular saying:

You can't give what you don't have.

The knowledge you don't have, you can't share. Then what happens to the one you share?

Things to note to get started

1. Platforms to write

While building your own platform is amazing, it's not always easy - considering time, and probably, current knowledge. The following awesome platforms which can help you with a platform for writing:

• Devblog - Hashnode: Devblog is a blogging tool optimized for developers, and it's free for solo-developers. Read more about Devblog
• DEV Community: DEV is a community of software developers getting together to help one another out. Read more about DEV

2. The fact that an article on that topic has been written before shouldn't stop you

Yes, that shouldn't stop you. While trying to learn Async/Await, I had to read over five articles (though not thoroughly, just trying to 100% understand a concept) - from MDN to Hackernoon to Javascript.info to two other articles on Medium. It's not like MDN was that bad, but the documentation there still left some questions of which I had to refer to other sources.

The way I write my contents would be different from you, because as humans, we're all unique. I may not come out very clearly on a topic, or may leave few confusions but yours may cover my everything.

Also, before I wrote on Web Share API, I searched online for articles on it, and I discovered many, even down to 2018. But I still wrote mine (with my acquired knowledge on it). When I published it and shared it on social media, I surprisingly had over 1000 views on the article (with the aid of google analytics) on the day of publishing. I also received feedbacks from people on how they were just discovering that feature for the first time. Remember, this is the same feature someone wrote about in 2018, but my article in 2019 was what introduced some other people to the feature.

Although, there's a feeling of achievement when you're the first to write an article on a topic, but asides this, what if your article is the article:

• someone out there is waiting for to get the grasp of a concept?
• that will introduce someone to an existing concept?
• that will show people that you know what you claim to know?
• that will proof to a potential employer that you are skilled in your field?

3. Do not be too driven by SEO.

Your article being on the first page of google when a phrase is searched can be indeed, a great achievement, but in my opinion, this shouldn't be your drive. Focus on delivery contents, adding value and simplifying whatever contents you place your hand on.

4. Stick to a commitment when writing

You wouldn't want to publish an article today, then leave your readers waiting till three months later, right? Just as it isn't fair with your readers, it also isn't with you. The benefits outlined above result from a committed approach. This is the reason why I decided to engage to #2Articles1Week challenge so I could write regularly.

There is an exception to this though - no free time. No free time can be a bad excuse and also a good excuse especially in terms of work schedule, school and the likes. Nevertheless, try to commit to regularly writing. It may be once a week, once a month or whatever it is, just be committed and regular.

Guidelines on effective approaches to technical writing

1. Use appropriate titles for contents, while also trying to get the reader's attention through it.
2. Start your article with a good introduction (if possible, table of contents inclusive) so that the readers would know what they are in for from the beginning of the article.
3. Try to appropriately use images and gifs if you can, as these also clearly illustrates your points.
4. Be succinct with your explanations. You wouldn't want to confuse your readers.
5. Wrap up your writeup with a conclusion which summarizes the topic, and possible, share useful resources.

There are better and more professional approaches, but you can start with the above. You'd improve as you continue.

Now, the FAQs

1. How can I get into technical writing?

There's no complex way of getting into it. What you must have in check is:

1. Do I have a platform?
2. Do I have a major field or I would be general (not too advisable) with my contents?
3. Am I really ready for this?

The last question is really essential. Technical writing requires passion - to teach and to learn. And just like I stated earlier, it needs commitment.

2. How do you come about content ideas?

Ideas come in various forms. Sometimes, when I learn something new and amazing through a resource or a video tutorial, I then make some extensive research on it and put up words to form an article.

Some other times, when I hear about a new feature or concept from people or social media, my next goal becomes to put an article on it. Extensive research again, and I write about it.

And other times, when I find it difficult understanding a concept or debugging an error in an application, inspiration comes to write about it the moment I've been able to overcome them.

On few occasions, I throw out questions online asking people if there's any concept they'd need clarity on.

3. You write a lot, and consistently. What encourages you?

The benefits listed above is part of my motivation. Technical writing is usually not easy - getting the idea, making research, then actually sitting down to write and review it. But the fact that I'm reaching out to someone somewhere while at the same time, improving my knowledge is what encourages me.

Wrap up

I'd also have to note this too:

There is no better feeling than you referencing your own article when you forget a concept 😆 - Anonymous

Right? It's a feeling I can testify to. Sometimes you'd forget stuff, go online, and the first article you'd find is yours 😎

Well, I hope this article clears all your doubts and hinderances holding you back from trying out technical writing.

If you have any questions, kindly reach out to me on twitter - @iamdillion