Decode64 Logo Adriano Luz

Tips For Designing A Developer Blog

I’m starting a new blog. And what a better way to start it than talking about how I’ve built it?

Usually developers write their first “Hello World” blog post describing all the languages, frameworks and coding techniques they have used to build the blog.

But unlike all developers, I won’t describe how I built it technically.

First because I used a quite ordinary set of tools: jekyll served from github pages.

Second, because I want to use this first post to set the expectation of what kind of topic intend to write about in this blog.

In this post I’ll discuss how I built my blog from a design perspective and give some tips about designing personal blogs for developers.

Let’s Talk About Design

The goal of any blog is to keep the reader’s attention to be able to deliver a message or knowledge effectively. For this reason you’ll notice that my blog has a really simple UI. Some may call it “minimalist”.

It is minimalist in the sense that all that I’ve done in the UI was just adding a few sprinkles on top of what browsers render naturally without any styling. You can see that not much changes if you render my blog without CSS.

The few changes added on top of a raw HTML were added with the goal to improve as much as possible the reading experience.

Here are the 7 main design elements that I used to build a better blog.

1. Limit Content Width

Perhaps the most important tip. Limit the width of the text.

Long lines are really difficult to read and to keep track of. When readers reach the end of the current line they won’t have the beginning of the line in their field of view if the line is too long. This makes it difficult to know which line is the next.

It will cause frustration and can make readers lose interest in the content only because the text is hard to read.

2. Don’t Add Distractions In The Middle Of The Text

No pop-ups, no animations, no ads. Nothing. You want your readers to stay focused on the text to be able to communicate your ideas effectively.

It is very likely that readers will already have other sources of distraction while reading your content. Don’t add another one.

3. Add Code Highlighting

Code highlighting is one of the best tools for software development and can be integrated into your blog to make code blocks easier to read.

It is also important to add highlighting for inline code snippets. Something simple like a text with different color using a monospace font is enough to make the inline code distinguishable from the normal text.

4. Display The Post Date At The Top

One of the most frustrating experiences for a software developer is to read an entire blog post, test the examples and ideas, fail to make them work and, after a lot of debugging, discover that the post is outdated.

For this reason, any blog, especially blogs focused on software development, should include the date of the post at the beginning of the page.

If you have an outdated post that you know that doesn’t work anymore, add a disclaimer at the beginning of the text. Another idea is to write a new post and add the link to the updated version on the old one.

5. Tag Your Posts

Tags are a simple way to give additional context about a blog post theme. But don’t add too many of them to a blog post.

Many tags to a single post means that the content doesn’t have a clear focus or some of the tags are irrelevant. Either case is bad for readers.

6. Avoid Default Visual Themes And Templates

A unique visual style to the blog allows the readers to quickly recognize that they are reading your blog. The blog UI is part of your branding.

For this reason, avoid default themes or themes that are used by many other developers. Try to come up with something new.

Keep in mind that the blog visuals should be simple. Remember, the goal is to improve the experience of the readers and not to distract them with fancy CSS.

7. Call To Action At The End

If a reader reached the end of your content, congratulations!

It means that the reader enjoyed your content and you can use this opportunity to guide them to a place where they can learn more about the topic.

You can add a link to a related post or a link to your social media where the reader can ask you questions or give feedback about your content.

Reading Experience

Everything is designed for someone to accomplish a specific goal. When designing a blog for developers we should think how the design will improve the reading experience and, as a consequence, help the readers to learn as much as possible.

Are you designing a blog? What design element have you added to improve the reader’s experience?

If you have any questions, comments or feedback, reach me on twitter at @decode64.
2021 © Adriano Luz