The pragmatic blogger
Blogging for developers: a practical effective checklist
Recently I had the pleasure (and fun) of speaking at JFall, the most significant Java event in the Netherlands. It was a lightning talk (20 slides — no more, no less — 15 seconds per slide — with auto-forward!?) and this blog captures the thoughts, ideas and tips discussed during the session.
In this article: pragmatic tips and examples for developers who want to write technical blogs. Based on a conference talk.
#1 Why you want to blog
Developers create technical articles for various reasons: I personally find this the best way to go deeper into the topic or project I want to share, effectively turning blogging into a learning opportunity. It is the moment when I can drill into the smallest detail or explore beyond what I have experienced.
Key takeaways: you can do it for learning, sharing or documenting, maybe building your public profile or contributing to projects and communities. They are all great reasons. Just do it!
#2 It is hard but...
It is not easy: it takes time, effort, creativity and, above all, a methodology. It can get frustrating when the words are not coming out of the keyboard, we get impatient and maybe a little bit edgy 🤬.
Never mind, here are some ideas, tips and provoking thoughts that hopefully can help or at least make you think.
Tip number #1 is to find your own framework and style, be different, and be original.
Key takeaways: you can learn from others but aim at creating your own style of blogging. Your story, your way.
#3 Few resources
Newsletters are curated and usually have high quality, so it is a good idea to subscribe to a few and learn as well as get inspired. Grammarly is an essential tool while Thesaurus can really help to make your article more elegant (think of synonyms and antonyms).
Images and memes (without exaggerating) are your allies.
#4 Structure… or no structure
There are lots of templates that can inspire you but I am not bothered, and nor should you. Focus on what you consider important: I find very important a good “Introduction” (convince your readers the article is relevant to them) and often try to include a list of “References” (developers love to follow up and continue the learning journey).
Key takeaways: the article structure may vary, but some elements are essential and should always have a place.
#5 Who is writing?
Establishing credentials is essential (the readers want to know about the author's expertise), but what is fundamental is to make clear from which point of view you are writing. Are you a developer sharing a lesson learnt? Are you teaching a framework or topic you know inside out? Are you sharing ideas, thoughts and rants? Pick your angle.
#6 Who are they?
There are different types of readers so you should try to identify the “persona” you are targeting. Developers like pragmatic examples (and love to copy-paste), while others might seek best practices or just enjoy learning about new technology.
Key takeaways: your style might the same through all the articles, but the focus can change. Favor snippets and problem-solving examples for (very) technical articles.
#7 Feed your audience
I often bring up the example of this successful article: the blog is full of snippets, config files, docker-compose, etc… I believe developers enjoyed the story of the migration (from NGINX to Traefik) as well as the many configuration snippets that might be useful in their own projects.
Key takeaways: code snippets rule. Pay attention to the format and indentation, keep it concise or link it with a Gist when it is long or becomes cumbersome.
#8 A good start
A good title is a must (everyone agrees) but I argue a subtitle is as important. Together, the combination of the title and subtitle can send a powerful message even before a reader starts going through the article.
Key takeaways: think how the subtitle can complement the title to give some extra context.
#9 TL;DR
Another tip is using TL;DR(“too long; didn’t read”) to present up-front what the article is about. Make clear why the article is relevant to the readers, and what they can expect. Convince them to invest their precious time to read it.
Key takeaways: title, subtitle, TD;LR…as you can see the beginning is very important. The context is made clear to the readers, you have already achieved some engagement and you can start the real story.
#10 Keywords
Make a list of keywords that include all aspects you want to cover in the blog post. It works as a sort of side note (reminder) that won’t let you forget thoughts and concepts that have triggered the idea of creating a blog post in the first instance (possibly days or weeks before you start writing).
As you progress through the writing and use these, strike them over, one by one. That gives also a nice feeling of accomplishment. 😎
#11 Visual is everything
No one likes to read a long crowded piece of text and would probably leave the page in no time. It is smart to create a friendly visual experience where the reader can easily glance at the content without unnecessary effort or confusion.
Make it scannable: it must be straightforward to skim the article and find the sections and elements that are interesting.
#12 Conversational tone
Adopt a conversational tone: it is simple, inclusive and friendly. A blog is not a manual or an essay, it should be something nice to read over lunch or while commuting. Contractions are your friends while not all words pay the rent and therefore can be evicted.
#13 Timeboxing
Write like you are on fire 🔥: your first version can be written from the start to the end in one go, without stopping. Just go with the flow.
Edit surgically: this is where you invest time and effort. Rewrite sentences, look for synonyms, and change the structure if needed.
Finally, review 3 times max: you have 3 lives and that is it, you are ready for launch.
Conclusions
I hope that sharing some ideas and tips can help you out, or at least can motivate you to find your own techniques and style.
Now it is time to get typing. Later.
