Are you looking to publish technical blog posts? If you are, it’s probably one or more of the following goals you’re after:
- increase the SEO footprint;
- build trust with the developer audience;
- decrease churn in your product or service by better informing your prospective customers;
- reduce the support load by showing your customers how to use your offering effectively.
In all of these cases, the blog posts you produce must be of high quality; otherwise you won’t see the positive results you expect. The components of high blog post quality range from a pleasant reading experience to accurate technical details.
In this article, we walk through 5 ways to improve the quality of your technical blog posts. Use these to update and tweak your existing writing, and have them in mind when creating technical content in the future.
1. Use clear writing
More often than not, technical writers suffer from a collective failure: they are so familiar with the jargon of the industry that they fail to break down familiar concepts in a way that the average user can understand. Even worse, some writers will forgo elements of style and precision in their writing in exchange for a quickly finished post. Not paying attention to the clarity of the text makes the average technical blog post too complicated to understand and more troublesome than helpful.
Trust in your reader’s intelligence, but also remember that there are more than six billion people that don’t speak English as a first language, many of whom have turned to tech and the internet for answers. As tech writers, we all explain complex topics by using clear, correct, and concise writing; we set the standard for knowledge sharing and exposition on the internet. Be knowledgeable enough about the material you are sharing with others that you can break it down into the smallest of components. If you can’t explain something in simple terms, there’s a problem with your information.
2. Test your examples
When searching for help, many programmers look to technical blogs for samples of code. Make sure to test the code examples in your technical writing to ensure that the code snippets you supply as an answer are usable in their present condition. If you provide an incorrect or failing solution, the user searching your post becomes frustrated. Finding inaccurate or incomplete answers on your website is one of the quickest ways for your users to lose trust and abandon your website as a possible avenue for solutions in the future. In extreme cases, incorrect examples can produce long-lasting effects on your industry.
Produce accurate, up-to-date copy with useful instructions that set your readers at ease. When you gain the trust of your users by only including correct examples in your blog posts, they will not only return to your site for answers but also share the information you provided with others.
3. Upload examples to a hosted code repository
Your website readers want direct and straightforward solutions to their issues. Copying an individual line of code can be useful for troubleshooting a small problem, but it’s unrealistic to make your users copy and paste fragments of code for large projects. To make it easier on your readers, make sure to upload the example projects that your article references to a code repository.
Consider uploading your entire project to a hosted code repository so customers can quickly and easily download what they need. Websites like GitHub, Bitbucket, and Gitlab can host large amounts of source code and assist developers in submitting patches of code in an orderly manner.
4. Share why you chose a particular answer
Every technical issue is unique, which means that one solution might not always fit all for users. To offer the most appropriate solution to users, technical writers not only have to focus in on a particular problem but also must show the method for achieving their singular solution. Like running a calculation in math class, a technical post should show the work that it took to accomplish the solution so that the reader can decide whether or not this method will be the right choice for their situation.
Clearly state why you chose this solution above all others. Clarify the limitations of the solution you have found, letting your readers know that it might not work for all situations, and offer another solution for a similar-but-slightly-different problem. Remember that you want your user to stick with you and trust you, not look to another source for another answer. Offering up an explanation along with similar issues and solutions and can increase the trust your readers have in your technical posts.
5. Use a readable font
A surprisingly common mistake in technical blogs is a lack of easy readability; the uglier your post by sight, the less likely a user will stay on your page. User-friendly interfaces and good, clear aesthetics are necessary to improve and keep your readers engaged.
To make things easy on your reader’s eyes, avoid using a font that is too small or a colour that that contrasts too harshly or blends in too much with your background. Keep it simple and easy, and stick with near-black text and near-white backgrounds for a professional, polished look. The text of a website body should range between 15-25 pixels; the body of your work should be large enough to make an impact and catch your reader’s eye. Commonly used fonts like Times New Roman and Arial will all appear differently sized on the page depending on their point size; test the sizes and see how they change as you modify your webpage. Don’t distract your readers with overuse of colour, images, or hard-to-read font. As always, less is more: deliver the point clearly and effectively.
Conclusion
Creating a quality article is essential, but the consistent quality is what will keep your readers coming back. Publish and promote your article, and you’ll soon grow with the feedback from your readers. With regular posting schedules, clear and concise examples and solutions, easily navigated and correct code, and a friendly appearance to your website, you have all the components to establish a solid structure that enables you to produce quality content.
