By June 20, 2018

Write That First Blog: Blogging for Programmers

Lately, I've been getting a lot of questions from friends and co-workers on how to write their first technical blog.

My advice? Just write it.

That's easy for me to say, though, as I've written prize-winning articles and even a published book. I've kind of got a head start as well since I'm not really a developer, but a schooled journalist (I only got into software development after graduating from university).

Here's the thing, though. I had to write my first article too. You may say you're not schooled to write articles, but I wasn't schooled to write software, yet here I am!

If I read my first article now, about try-catch-finally in Visual Basic .Net, I can't help but laugh at its simplicity. I was programming for about four months, my employer decided some co-workers and I needed some training, and so someone came over and taught us the basics of .NET, of which try-catch-finally blocks was one.

So I decided I needed to practice this newly gained knowledge and really get into it. Since I had been reading a lot of articles on CodeProject, I decided to try my luck at writing an article. The article, while pretty simple, became quite popular.

And so I hear you say I was eventually schooled in the topics I wrote about, while you are still not schooled in how to write articles. Let's talk about my second article.

You may want to read it, except you can't. No one can. It was bad. So bad it wasn't accepted to CodeProject, and I deleted it altogether.

However, that article is still the best article I've ever written. Not because the article was so good, obviously, but because there is no single article or even book that taught me more than that article. The article was about some object-oriented programming (OOP) concepts, which may sound interesting, except I didn't know what object-oriented programming was.

Needless to say, the article got very negative feedback; unfortunately, the internet isn’t always a friendly place. People called me an idiot and told me I shouldn’t be writing articles.

I didn’t let it get me down though.

I swallowed my pride, kindly thanking the reviewers for their feedback and asking if they could direct me so I could improve. Ultimately, I got to learn about OOP, SOLID, and design patterns.

It changed my life for good. My next article was about anti-patterns in programming, and it won Article of the Month on CodeProject.

If you want to start writing articles on a regular basis, you'll first need to understand what matters in an article and how to overcome the difficulties of writing.

What Matters in Your Article

The first question I often get from programmers who want to start writing blog posts is about writing style. How do you speak to your audience?

My answer: Personally, I like to write as if I'm talking to the reader. I use words like “I,” “you,” and “we” in the hopes that it's engaging to readers.

Other than that, I try to engage people by asking questions. Sounds hard, right? Well it really isn't. (See what I did there?) Many people like my style of writing, but I've also had complaints that my style is too informal, making it difficult to follow.

Another style I often see is avoiding words like “I” and “you” by using “one.” An example: instead of “you should implement an interface,” they write “one should implement an interface.”

My first thought is always, yes one should certainly do that, but what should I do? Personally, I'm not a fan of “one,” but if you feel more comfortable using it, don't let me hold you back. It may take you a few articles to find your own style. At the end of the article, only one thing matters: Has my audience learned anything?

If people wanted to read well-written literature, they wouldn't be reading technical blogs, but Shakespeare (or whatever they're into). Sure, your blog will read a lot better if it's grammatically correct, if your style matches the reader's preference, and if it's generally of top quality, but that's all pretty subjective and often not a deal-breaker.

Mind Your Language

That brings me to another point: language. Many would-be writers fear that their English is not good enough to write an article.

First of all, even if English isn’t your native language, that doesn't mean you can’t write a good article. Second, the goal of your article is to teach people, so code samples often matter more than grammar. I've seen articles with poor grammar win competitions because they were technically interesting and accurate.

Needless to say, your article needs to have a certain level of readability. If your grammar and spelling are bad, readers will have a difficult time reading your article. For this reason, I recommend a proofreader.

By the time you read this article, at least three people will have read it: a proofreader, who checks for spelling, grammar, and if everything is in the Simple Programmer style; a content editor who checks for content, flow, and correctness; possibly someone who checks for technological accuracy (not applicable here); and myself.

My latest book, Continuous Integration, Delivery, and Deployment, was proofread, edited, proofread again, checked for style, and then read for technical accuracy by four different people (and I still found a typo in the published version).

I'll tell you another secret: Simple Programmer has a plugin installed, called Yoast for SEO, that checks if my text is readable. It checks if there aren't too many words per sentence or paragraph. It also keeps track of headers and words under a header. There also appears to be some readability index (Flesch Reading Ease), and more.

Even professional writers need a little help!

If language really is a problem for you, I suggest you find someone who can help you with that. Or write in your native language, if that's an option. Your article will not reach as many people, but at least you've written something. While most of my articles are in English, I've also written some Dutch articles.

Illustrate Your Points

A picture is worth a thousand words, or so they say. Since you can only explain so much using words, and because written language may not be your strongest suit, be sure to use pictures. You're probably writing about code—maybe some cool trick, a design pattern, a framework, or a library—and images can reveal even more about it.

Imagine that you want to make it clear to your readers what the model-view-controller, or MVC, pattern is. You could explain it as, “A user calls a controller, which creates a model that is passed to a view, and returns that view to the caller.” But your readers are not going to understand MVC just by reading that. So add an image like the one below:

model-view-controller pattern structure blogging for programmers

Structure of the model-view-controller pattern [source: Wikipedia].

I'm pretty sure that image clears up a few things for the reader. Just the text didn't help much, but remember, just the image won't make a lot of sense either. Combining them can help get your point across.

How-to articles can especially benefit from lots and lots of pictures. It's just easier to point out a checkbox on an image than it is to describe where to find that checkbox.

Be careful though—not every article lends itself to extensive use of images. If you're focusing on code samples, it is much more important that your code is clear, concise, and most importantly, well explained than it is to have lots of pictures.

If you decide to add pictures, make sure they are of good quality. In my experience it's better to have no pictures than to have unreadable or blurry pictures.

Also, make sure you are authorized to use the pictures. Either they are yours or you have permission to use the pictures and mention the source.

You may use royalty-free images. Wikimedia Commons has an extensive collection of royalty-free images and images you can use if you follow certain publication rules.

Also, sites like Thinkstock or Shutterstock will sell you a subscription to their image libraries, which, if you're writing quite a few articles and self-publishing, could be a good investment.

Pictures saved from Google image searches are not OK to publish without permission. There are a lot of misconceptions about this. So if you take an image from the internet, be sure to check whether you can use it and under what conditions.

Explaining Everything

Here's something I like to do: Explain everything my code does. That sounds like an open door, but it really isn't.

If there is anything that the reader cannot be expected to know, I'm mentioning it. For example, I’m talking about Entity Framework and my sample shows a property:

The reader can be expected to know what a property is and what the public access modifier means. Also, the generic ICollection should be reasonably familiar.

However, what the reader is not expected to know is why we need an ICollection instead of the less specific IEnumerable or the more specific IList, and why it needs to be virtual, so I like to explain that.

Another fun fact is that the implementation of ICollection, Collection, isn't a widely used collection type because it's not in the System.Collections.Generic namespace, but in the System.Collections.ObjectModel namespace (due to some name clash with the old Visual Basic Collection type). Because of that, it's rare to see the ICollection interface at all.

I like to mention such details, as the reader might be wondering about this himself, and it saves the reader the trouble of looking it up. If I notice a detail like that, but I can't find why things are that way, I mention that too.

If you haven't noticed such details you can't write about them. It's not a big deal, but it simply makes you less thorough (which is also fine).

It Depends

As is often the case in software development, sometimes the most important aspect of your article is “it depends.”

What matters in your article mostly depends on your audience. Your audience could be teens or adults, boys or girls, but in our case it’s probably the level of experience of your audience that decides whether you’ll explain code in more depth, if you add more images, and whether you’ll expand on certain concepts.

As I said, your audience is probably reading your blog to learn something. Maybe you've written about Entity Framework or LINQ and the reader is trying to get a better understanding of the subject. If your post is an article for beginners, it's very important that you explain as much as possible in great detail, and that you keep your examples simple and build up difficulty toward the end of the article.

If your audience is senior developers with years of LINQ experience, you really don't have to explain how lambdas work or the difference between IEnumerable and IQueryable.

Also, if you are describing how you build an entire system, you probably don't have the time or the space (or the reader’s attention span) to explain everything in great detail. Explaining the bigger picture (possibly with some pictures and some code samples) will suffice.

Code Samples

If you're doing an article on a piece of code, probably more important than anything in your article are your code samples.

I write my code for articles differently than I write my code for work. At work, I'm assuming my code will be read by professionals who know what they're doing.

When I'm writing an article, I'm expecting my audience to be a student. For example:

Would be written as:

The latter isn't necessarily better to read; I'd even say it's worse to read. But it may be easier to follow for a specific code sample in an article.

Besides being easy to follow, your code should be well-formatted. While your IDE, like Visual Studio, is pretty good at formatting your code, your blog page usually isn't. Blogs often have a relatively small width reserved for text, so your longer lines of code will be cut off in the middle. Depending on your CSS, your code will go beyond the borders of the page or continue on the next line.

There are some WordPress plugins out there that can format your code. If you write for another website like Simple Programmer, which uses GitHub Gists for code samples, or CodeProject, syntax highlighting may or may not be enabled or may not be what you're used to.

When you're writing a book, your code has to fit a page and will be printed in black and white, so it’s best to keep your lines of code short and readable. For example:

var result = people
    .Where(x => x.Name.StartsWith("A"))
    .OrderBy(x => x.Name)

Instead of:

var result = people.Where(x => x.Name.StartsWith("A")).OrderBy(x => x.Name).ToList();

But here's an even better alternative (which I've already used up to this point):

These are three pieces of the exact same code, one unformatted, one formatted, and one formatted using a third-party code formatter (a GitHub Gist). I'm guessing you prefer the GitHub Gist for readability, even though it's the exact same code as the previous sample.

The Hard Parts of Writing Blog Posts

Writing a blog post isn't really that hard as long as you know what to write about. For me, the hardest parts are always coming up with a topic, creating a sample project (if applicable), and writing a first and last sentence.

As I said, I like to write as if I'm speaking to the reader. The first sentence is synonymous with walking up to a complete stranger and, out of nowhere, starting to talk about programming … awkward. Likewise, the last sentence feels like saying something and then walking away.

Opening Sentences

The topics and samples are up to you. I can help a little with the first and last sentence though. A good starter can be, “In this article, I want to discuss…” or, if you're doing a series, “In my last post, we talked about…[past topic]. In this post, I want to follow up with…[new topic].”

Or you can start with what led you to write a specific post. In this case, I was asked how to write a blog post as a programmer, so I decided to write a blog post (re-read the lead sentence). Other personal examples include, “I am currently studying for an exam…” and “Well over a year ago […] I witnessed a lecture…”

In the introduction, make sure to mention why others would want to read it too. If I write this to study for an exam, then certainly someone else can learn from it too.

You can also “just start.” My first article started with “Error handling is an important part of software development…” Another started with “The .NET Framework has provided collections of different types…” The upside to this approach is that it's clear what your post is going to be about and why anyone should read it right from the get-go.

Closing Sentences

At this point you've said everything you wanted to say. You can just abruptly stop the article, but personally, I like to recap what we've discussed and what you can do to get better (mostly keep practicing).

You can also announce what your next post will be about. Additionally, you can say that you'll be happy to answer questions in the comments. If you've found some cool new stuff while writing the post, you can mention that you've learned a lot from writing this as well.

For example, “Well, that's it! I've certainly learned a lot from writing this down. I'll be happy to answer any questions in the comments.” It's a bit friendlier than just stopping abruptly.

The Sentences You Don't Write

Last, but not least, it's important what you don't say. As I said, you want to explain as much as possible, but in varying depth.

If you explain a piece of code and you spend 500 words on a single detail, it would feel weird to discuss another, equally important detail in just 20 words. Likewise, it would be weird if you spend 500 words on an unimportant detail, when maybe just mentioning it briefly would have sufficed.

There's also so much you can say. For my blog posts, I usually keep a range of 2,000 to 3,000 words. I plan to discuss a couple of concepts, say four, so I have about 500 words per concept. Maybe I'll need 400 words for one concept and 600 for another, but I probably can't use 1,000 for a single concept. Maybe you want to discuss those four concepts in depth and then mention another two or three concepts to push the reader to explore further; it’s really up to you.

For example, I've written a blog post about NoSQL and MongoDB. I spent about a third on NoSQL in general and two thirds on MongoDB. I spent a single paragraph on installing MongoDB, and I mention you can do all kinds of stuff from the command line, but I'm going straight to C# code for this article. We cover the basics of CRUD, but I also quickly mention you can insert complete lists.

For that article, I decided to write it so it’s just enough to get started, but not enough to be proficient. It's a choice, but one you should make up front before you find yourself writing way too much.

If you’re struggling with this, it’s a good idea to write an outline of your blog post first. An outline is like a small, private table of contents in which you write down the topics you want to discuss in the order you want to discuss them.

Now Get to Writing

Now it's up to you! Make a blog, or maybe you already have one, or find a website where you can write your own articles.

There are plenty of resources on the internet to get started. There's even a free course on Simple Programmer that helps you create your blog. So you really have no excuses not to get writing!

And once you get to writing, be sure to keep going at it!

I'll be happy to answer any questions in the comments.

Good luck!

About the author

Sander Rossel

Sander Rossel is a professional developer since 2010 with working experience in .NET and .NET Core (C#, ASP.NET, and Entity Framework), SQL Server, Azure, Visual Studio Team Services, JavaScript, and other technologies. He has an interest in various technologies including, but not limited to, Functional Programming, NoSQL, Cloud, Continuous Integration, and software quality in general. You can't miss his must read book Continuous Integration, Delivery, and Deployment! He also wrote the +/- 100 page eBooks Object-Oriented Programming in C# Succinctly and SQL Server for C# Developers Succinctly. And he wrote a JavaScript LINQ library, arrgh.js (works in IE8+, Edge, Firefox, Chrome, and probably everything else). Check out his prize-winning articles on CodeProjectas well!