SBN

Writing for the Web

A guide for writing better technical articles + blog posts

Photo by Andrew Neel on Unsplash

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.

Simplify

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 that makes sense. This makes it easier for readers to revisit, share, or reference different parts of your article.

Edit

Let’s be honest. Your first draft is horrible. The first draft of this post was significantly more horrible than the version you are reading now. That’s why you should always edit your blog posts.

First, check the organization of your article. Does the article say everything you want to say? Does it do so in a structure that makes logical sense?

Next, delete any sentences or paragraphs that do not add meaning or value to your article. Remove redundancies, wishy-washy phrases like “I think,” “you should,” and “probably.”

Finally, check for grammar issues, either manually or with a grammar checker.

Most of the time, editing cuts the word count of my first draft down significantly. That’s a good thing! It means that the article is becoming more precise, direct, and clear.

What about writer’s block?

But what about writer’s block? One of the issues you might encounter when writing is simply coming up with the next sentence, paragraph, and so on.

If you already have a topic in mind, a good way to combat writer's block is to start with an outline. Create an outline, layout the headings and subheadings, then fill out each section. This will help you stick to a clear article structure as well.

Another way to combat writer's block is to just start writing! A lot of writing difficulties are caused by inhibition. When I am writing, I often find myself self-editing and nitpicking about the details of my blog post. I become self-conscious about how my writing will be read and become unable to write naturally. In this case, it is important to remember that you will be editing the article later on. So for the first draft, just write whatever comes to your mind! Use bad grammar, use wishy-washy words, and don’t think too much about the tips I mentioned in this article. You can always edit it later.

And as always, have fun! Writing technical blog posts is a fantastic way to share your learning and make friends with the same interests. If you would like to share your blog or your blogging experience with me, feel free to connect at https://twitter.com/vickieli7.


Writing for the Web was originally published in ShiftLeft Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.

*** This is a Security Bloggers Network syndicated blog from ShiftLeft Blog - Medium authored by Vickie Li. Read the original post at: https://blog.shiftleft.io/writing-for-the-web-f2c9acf440c6?source=rss----86a4f941c7da---4