Technical Writing: How Do I Get Better at it?
“How can I improve my technical writing skills?” This is a question I’ve been asked a couple of times. I’ve been writing technical articles for about three years now, so I’ve gained a lot of experience in this area, and in this article, I’d like to share a few tips to help you improve.
“Do you think I should write this article although I am not a native English speaker?” Is a question that has prevented many people from sharing their knowledge in writing because they are unsure of their ability to express themselves properly. My usual response is to give it a shot; with repeated writings, you’ll be able to improve your ability to express yourself. Don’t let this be a hindrance to you, I mean few of us are English speakers!
That being said, let’s look at some of the tips I feel are a great addition:
Don’t be afraid to write
Many are the times you’ll be stuck at thinking if you should really write about a certain topic. I mean, there’s already someone who’s already written about it and why would you bother, You may ask yourself. If you heed to this, truth be told, you’ll never get yourself to write. And yes, someone has already written about the topic, this doesn’t mean you shouldn’t write. Every writer has a different way of expressing themselves and explaining something. And in such even if two writers have the same topic, both can be able to give fresh perspectives about the topic. You should, therefore, seek to give different perspectives that other writers have not covered yet. Seek to explain in a way that has not been explained before and this makes you stand out.
Avoid plagiarism at all costs!
In the spirit of giving a fresh perspective, you might find yourself in the temptation of copying other people’s work or copying the entire documentation in your article/tutorial. This is very wrong and makes you seem not serious with your work at all. Always makes sure your work is original and if you have to reference other people’s work, give all credits where it’s due since authors take a lot of time to come up with a writing moreso a technical one.
Have a Sample Project
At times a reader may be stuck in the middle of your article and having a sample project on GitHub, Gitlab, or even Bitbucket or your chosen Version Control System really adds value to your writing. It serves as a point of reference in case of any errors and also to some readers who would be interested in checking the final solutions and do not want to read the whole article.
Make all instructions clear with no errors
Most documentations need improvements when it comes to making instructions clear. This at times makes you lose a potential reader or even a library user. It’s usually frustrating at the very least, for example, you try out a library for your first time and find out that instructions on the README.md do not work as outlined. As a writer make sure you review all the instructions in your documentation and article to make sure they work as expected and are very clear. Make no assumptions and make everything explicit rather than implicit. Avoid having magic functions, variables, classes, etc. This for me is usually the most important rule in any technical writing I have to do.
It also saves you time as a writer since you’ll not be having back and forth support issues. It’s usually a deal-breaker for most technical writings. Imagine you have a 30 minutes article and some instructions fail at the very start, this means the reader is stuck at that point and most of the time they’ll just stop at that point.
Ensure you pay enough attention to this and review it a lot of times.
Do Research Before you Write
It’s important to do thorough research on the topic you’re to write about or even the documentation you are about to write. This simply gives you an overview of what has already been covered and what you need to be covered. If a topic has been already covered a lot of times, it’s wise to not write again as your content will not be as that fresh. Unless you can provide a unique perspective, I would urge you to not do something that has already been done multiple times.
The research helps also in structuring your content in a way that it is fresh and does not get boring. Remember you’re writing on technical topics and keeping them interesting is one of your goals too. The reader has to be able to follow along and grasp concepts even when they’re so complex.
Read From other Authors
For you to be a good writer, you have to read a lot ~ Harun 2021
Wait, did I just come up with a quote :-) The thing with reading a lot is that it also gives you insights into different writing styles and ways of explaining complex ideas in a way a reader would understand. You’ll find some authors use real-life examples to drive their point which you can also add to your writing when faced with scenarios where you can not simplify a certain concept. Also, you get ideas on how to sprinkle humor in your article to keep it interesting to your reader. With so many amazing people producing content on a daily basis, it’s hard to read all of them but be sure to read every now and then. You can even get your next topic as you read someone’s work as maybe you might see the necessity to explain something in a way the author had not explained. And as you read, remember, do not copy other’s people work.
Have someone review for you
Having someone go through your writing and check for things you might have missed or mistakes you’ve made greatly improves the quality of your writing. You can have experts in the domain reviewing and also even non-experts in that domain reviewing it too. This helps since they’ll be able to find the missing gaps in your writing and help you fix them before you make your work available to the general public. Take their feedback and don’t be discouraged by whatever feedback they give, it’s meant to improve your work and not pull you down.
Identify a niche
In every domain, there’s usually so much that can be written about. It’s easy to get trapped in the writing about everything issue. This means you don’t get to focus on a specific area and this greatly affects the quality of your writing. It’s great to choose an area and focus on it.
Having a niche also solves the biggest questions which make so many writers stop writing: What do I write about? Since you have a niche, you’ll also find topics to write about.
Plan, plan, and Plan!
We writers usually have so many topics on our to-write list. So many articles on draft that never get published. It’s very essential for you to plan for your writing. As such you avoid having so many undone articles. In my case to avoid procrastination, when I usually have a topic to write about, which at times can take forever :-( I usually dedicate let’s say a weekend to do the writing and sample project. During this weekend I wouldn’t want to get distracted until I finalize working on the article. After coming up with a draft, I normally take a break like a 12-hour break, and then review the draft when my mind is fresh and then share it with some to review then go-ahead to publish. With this approach, I have found myself completing so many drafts as I know once I start on a draft I will have to complete it by all means!
The problem of having too many drafts is at times it can be overwhelming and also your content might be stale due to the long period. And again, once you have a draft in the works for a long time, you tend to get new perspectives and tend to re-write the article every single time and the cycle never ends!
I had the problem of having too many topics on my to-write list which to this date never got to see even a one-paragraph draft. For me, to address this, I saw an opportunity to join raywenderlich.com as an Android Author which I gladly applied to and was able to join the amazing team here:] With this, there are deadlines and ready topics for you to pick and write about. So once I pick a topic I know I have to commit to deadlines and make sure I complete the tutorial. This has really helped me churn out tutorials every 3 months or so which was quite a hard thing to achieve the other years. I could only manage to write like 2–3 in a year. Now I can even do 5–6 in a year which is a big plus!
That was my approach, you can always find what works for you and a way to keep you accountable.
Avoid knowledge gaps
You also have to go out of your way to know everything about your topic and also the domain in general. Continually seek to learn as you’ll also find readers asking so many tough questions and if you don’t have enough knowledge on your topic, these gaps will be very visible and are very embarrassing. So it’s good to be knowledgeable enough and you’ll be in a position to help out readers even in their certain use cases as people have different use cases apart from the one you’ve written about.
Consistency and Feedbacks
Once you stop writing, it’s hard to get back at it. So be consistent and write more often than not. A good thing is to take feedback from the audience you write for. This helps you improve both your writing skills and communication skills and make your consecutive writings so much better.
Don’t write just cause you can!
I have the skills to write, and all the topics in the world to write about. “Do I publish an article every day?” It’s very easy to fall into this trap. And my answer to this is the famous one: It depends! Writing and publishing every day at times can mean you compromising on quality and no value addition to your readers and in this, you’ll lose so many readers as they would want to see the value after they read. If you can be able to publish daily and not compromise on quality then why not, you can publish as much as you can.
Another problem with publishing daily is that you don’t get breaks between your writes and your style can become monotonous. Breaks are very important for creativity purposes too and help in making your content fresh.
So, don’t write just cause you can!
Conclusion
Woohoo! That was quite a read. These are from my experiences from writing at raywenderlich.com and on medium too. I’m not saying you follow them to the letter as our experiences are usually very different and what works for me might not work for you.
Feel free to add your tips in the comment section. And finally, let’s continue to be amazing writers as the tips shared here apply to technical writings and also documentation for libraries and open source projects too.
Hope you enjoyed this!
