How to Write Blog Posts if You’re Not a Blogger

How to write properly and make your posts look more attractive if you’re much more of programmer than professional blogger.

I’m a programmer and I read a lot. I read a lot of technical blog posts, too. But the truth is that I can’t finish the most of them. Too often, the language is so hard to read, the structure is so terrible… Even if the idea behind the post is good, it’s often hard to fully appreciate it.

Let’s say you’re one those programmers who think that they have something important to tell to other programmers. However, it’s not enough to just write down your stream of conciousness. You could, of course, but the most of people will not appreciate it. Here are some rules that will help to convey your idea, make your blog nice to read and even, if you’re on the Medium Partner Program or similar, make a little bit more money.

Structure

Think about structure of your text. First of all, it must be separated into parts. Each part must have its own meaning. No by-the-way inserts, only related information. If you’re a programmer, you must know about the Single Responsibility Principle. It is true for texts, too. Every paragraph, every single block of text must have its own purpose.

If you’re a programmer, you must know about the Single Responsibility Principle. It is true for texts, too. Every paragraph, every sinlge block of text must have its own purpose.

Each block of text also should have clean structure. It starts with the main thought, then goes into details, maybe gives an example, and ends with conclusion. This is applicable to every layer of abstraction: paragraphs, sections and the entire text.

One sentence is a single thought. Thoughts should be explained one by one, sentence by sentence, moving up the chain.

Form

The shorter the better. No excess figures of speech. Clear, simple and straight to the point.

Keep to one tense. Be consistent with your narrative style.

Another rule of thumb is to abandon your own conclusion. Facts are what is really important.

Presentation

Visual components are very important. When formatting is poor, even if the text is a piece of art, it’s very hard to force people to read it. Beatiful and, not least, meaningful text formatting attracts and makes it easier to start reading. No one likes unattractive posts.

Don’t forget about headers, subheaders, quotes, highlighted important parts, hyperlinks, code examples, illustration images, etc. Not to mention that images usually make complex topics more easily understandable.

Images make complex topics more easily understandable.

While dividing your text on modules, don’t forget about structure. In the perfect situation, each module could be read separately, as if it was a stand-alone article.

Reading Out Loud

Your writing may seem perfect — beautiful language, structure, good sense of humour… But when you read it, you stumble now and then, or even worse, you constanly start reading sentences from the beginning. Reading your text aloud will help avoid such problems and fix places where it’s hard to read.

Proofreading

Use a spell checker. If you have a grammar-concious friend, ask them to read your piece. If you write not in your native language, ask a native speaker for help. These simple actions will have a drastic effect on the result.

Code Snippets

This one is totally controversional but I couldn’t let it rest. Don’t use Github Gist and other third-party services for your code snippets! I know, they garnish code, with all that nice syntax coloring and stuff… But the way they make the web page jump while it’s downloading and rendering drives me crazy.

Beside all afrementioned you should remember two things:

  1. Rules are made to be broken. If you think that neglecting one or another makes your text more interesting, just do that. If you want to find an audience, in the first place, write as for yourself.
  2. Your post will never be perfect. No post will. If you’re a software development related person, you must have heard a Reid Hoffman’s quote, If you are not embarrassed by the first version of your product, you’ve launched too late. The same can be applied to blog posts.

If you are not embarrassed by the first version of your product, you’ve launched too late. The same can be applied to blog posts.

Those are main rules that help me to write. But you what? For me, as a programmer, not a professional blogger, those principles are not about leads and money. They help building more confidence and make the Publish button less scary to me.

Where to Go from Here?

The absolute classic is the William Strunk Jr.’s Elements of Style — a must-read book for everyone who wants to write.

If it happens that you’re a Russian speaker, a very good book about writing good texts in Russian is the М. Ильяхов and Л. Сарычева’s Пиши, сокращай.

A Programmer’s Guide to Writing Your Heart Out — this is my thoughts on why writing is good and how to start doing it (again, especially, if you’re a programmer.)

Swift and general programming topics, Agile software development, soft skills

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store