8 Technical Writing Tips I Learned From Writing For SitePoint, Draft.dev, and More
This article was originally published on my personal blog
Late 2020, after writing articles sporadically, I finally created this blog. Through this blog, I was able to write many articles and tutorials about Javascript, Browser Extensions, Magento 2, and more.
Then, in May 2021, I branched out and applied to write for different platforms. I landed a couple of gigs and became an author for some notable websites or agencies like SitePoint, Draft.dev, LogRocket, ContentLab, and more. Check the My Guest Writings page to see some of them.
After writing for these websites or some of their clients, I learned so many things regarding different technologies. I also learned some tips that allowed me to improve my technical writing. In this article, I'll share some of them with you, and in the end, I'll add some links in case you want to apply to these platforms, as well.
Start with an Outline
Previously, I would get an idea or a concept I'd think would be good to write about. Then, I'd start writing right away, or if it's a tutorial I'd start coding in parallel. However, when I started writing for SitePoint, I was always asked to provide an outline before I start writing an article. Similarly for Draft.dev whenever I was assigned an article, it always starts with an outline.
Defining an outline for your article organizes your thoughts and ideas before getting into them. You might have a lot of useful knowledge to share, but it gets lost between the spontaneous sentences here and there. Outlining the topic's headlines first allows you to organize where each thought, idea, or tip should go.
If you're not sure how you can write an outline, there are some tutorials that can help you get started. However, you can also start with outlining articles in your thoughts if that's easier. Take time to plan how the article's structure will look, and once you think you're confident enough in the planned headings and ideas flow, you can start writing the article.
Simplify Tutorials
When a certain section in your tutorial requires setting up something that isn't actually necessary to the topic of the tutorial, simplify that as best as possible. Here's an example: let's say you're doing a tutorial on something related to Node.js. You might need to store the data somehow, so you end up choosing MySQL as the database. So, you'll have to add setup instructions in your tutorial related to setting up the database, when it's actually not necessary to the tutorial.
This can cause confusion, especially if the reader doesn't know about MySQL (in the example I'm giving) enough to keep up, or maybe they don't have a MySQL server installed on their machine anyway. Make sure your tutorials are simple and to the point. Even if something seems simple to you, it might be a hurdle to the reader and they end up leaving your tutorial trying to find a simpler one. In the example above, if you need to use something to store the data you can try using something simple like an SQLite database where there won't be any complicated configurations required. Even if the reader doesn't know anything about it, then don't really need to know to keep going with the article.
Stay Consistent
When writing an article or a tutorial, it's important to stay consistent. This applies to many things. First, don't use different spellings throughout the article. For example, don't use Javascript at one point then use JavaScript at another. Second, make sure your code is consistent. Don't use " at some points then use ' in others, or don't omit ; in some code blocks and leave it in others. Although these details might not seem like they're a big deal, providing consistency keeps your article organized and uniform.
Don't Assume The Reader Knows
A lot of times we use certain words, phrases, abbreviations, or overlook details thinking they're basics and just like we know them, the reader will know them as well. It's important to cater your articles to readers in general.
When using abbreviations, you should at least use the full word or phrase once with its abbreviation, then you can use the abbreviation after that. For example, if your article mentions Create React App, you might be inclined to just use CRA. Instead, the first time you mention it you should do it as "Create React App (CRA)", then refer to it as CRA in the rest of your article.
When it comes to tutorials, for example, using methods, try to link to documentation on that method even if your tutorial explains it briefly. This allows the reader to delve more into the details if they need to and see any additional details you might have overshadowed as they don't necessarily fit into the tutorial. You can link to documentation from MDN Web Docs or other websites depending on the programming language you're using.
Always Link to Sources
Similar to the previous section, you should always link to sources when possible. If you mention a survey or study results, browser limitations, quotes from other articles or books, or anything that comes from an original source, link back to it. This builds your article's credibility and maintains trust with the reader. Also, it allows the reader to check it out for themselves and see the details if needed.
Create a Style Guide
When you first start writing articles, you might not care much about following a certain guideline for your articles. However, for the consistency of the blog as a whole and to maintain a certain structure for your articles, it's good to have a style guide. A style guide that an article must follow includes the type of headings it should use, certain words or formatting of the content, and other rules you can add yourself that you find are helpful through your journey in writing. You might be confused on how to start, but the more you write and start understanding the kind of blog you're creating, the clearer it comes.
Try to start by creating a certain guideline for the content formatting. For example, a new line should be added before every new section or after every headline in the article. Start with simple guidelines and grow the list with time.
Have an Average Word Count
A good tip I've learned by writing for all these different platforms is to keep an article between 1500~2000 words. You don't have to always keep the article in that range, but it's good to have an average range just to keep yourself in check and know when an article can be shortened or split into parts, or when it should be longer with more details.
A lot of times I write a long article, then I take a second look at it and realize that I repeated myself a lot of times unnecessarily. After writing an article, if it's too long try to remove any unnecessary details or repeated statements. Make sure the article or tutorial focuses on its main purpose rather than unnecessary details. This helps the reader to get the best out of it when reading it and not get lost in irrelevant details. If it's a tutorial and can be split into parts, do that as it will be easier for the reader.
On the other hand, if an article is too short take a second look at it. Are there ambiguous details? Is there room for confusion or misunderstandings? If so, take the time to re-iterate or elaborate on what you want to say or teach the reader. A lot of times we think that our point is coming across well, or what we are trying to teach is easily understood, but in reality, the article ends up missing the main point.
Learn and Write
Before I started writing, I got to a point where I stopped learning new things. I just stuck to what I knew and never evolved. When I started writing, I started expanding my knowledge and learning new things to write about. Especially when I started writing for platforms like SitePoint or Draft.dev. A lot of times I was assigned an article that I had a basic knowledge of, or some I barely knew anything about. However, because I had to write about it for an article, I researched and went deep into the details of the topics. This helped me learn new things and expand my knowledge. I wasn't only writing to help others, I was learning through the process as well.
Bonus: Be Confident In What You Know
A lot of people want to write but are scared that their knowledge is nothing compared to others, or that it will not benefit anyone. I felt the same way too when I started this blog. I thought that what I knew everyone knew, and that writing about these topics will not benefit anyone. However, after I started writing about all the different topics I had knowledge of, I received so many messages and emails thanking me for helping them resolve an issue they faced, learn more about a topic, or help them understand some things more. Even if you think your knowledge is limited, that does not mean others can't learn from you. None of us know everything, and someone is bound to learn from what you have to share.
Additionally, even if no one reads or benefits from your article, you'll benefit yourself. Every single article or tutorial I wrote I learned something new from it. Sometimes it's minor details when I'm trying or searching for something, sometimes it's the entire topic. At the end of the day, there's at least one person learning from your writings, so be confident about it.
Conclusion
If you're considering writing for these platforms, don't hesitate or think you can't do it. You can always apply and try, and hopefully, you'll learn through writing for them as well.
I'll leave the links to apply to write for these websites below. Take the time to go through them if it interests you.