A guide for writing better technical articles + blog posts
One of the questions I get the most in my Twitter DMs is “How do I write better technical blog posts”?
Technical writing is a specialist skill, and I am by no means an expert. But over the past few years, writing my technical blog has taught me a lot about writing for the Internet. So today, here are my tips to help you produce better technical articles.
Good writing is easy to read. This is especially true when writing on the Internet. On the Internet, your technical blog post has the potential to be shared anywhere in the world. You never know who will come across your content and what their background will be. Simple articles allow non-native speakers and novices to consume your article. Short sentences and paragraphs also make your article easier to read for people using mobile devices.
You want your content to be understandable by the largest group of readers. So it is essential to keep it simple. I am not suggesting that you dumb down your technical content. But you should try to use simple words and sentence structures whenever possible. Avoid jargon, abbreviations, and obscure references. And when you can explain something with one word, never use ten.
Next, simplify your sentences and paragraphs. The rule of thumb that I use is “one idea per sentence and one concept per paragraph.” Do not try to say too much in one go. Keep sentences short. If your sentence is getting too long, divide it up to two.
Chunk it up
Writing a blog post is not like writing a research paper or a book because the way people consume information on the Internet is different. When people read your blog posts, they might scan the entire article before committing time to reading it. They might be browsing Twitter or checking their phones at the same time. They might be reading your article on a tiny smartphone screen.
So when writing Internet content, it’s important to deliver a good digital experience. Divide your article up into easily digestible chunks. Ensure that each section is marked by appropriate headers and subheaders and that you are introducing concepts in a sequence…