At work, I've recently been asked to advise our engineers on how to write blog posts. A lot of such articles are already available. However, they tend to focus around two main themes:

• The technical publishing platform e.g. Jekyll, Medium, etc.
• Metrics e.g. readability score, SEO, etc.

Beyond that, everyone is on one's own. But I believe that writing a good technical article is as much art as engineering.

In this post, I'd like to try to address this gap: I've been writing this blog for more than a decade. I hope I've learned some things along the way, so here are my advices.

Note that they are solely based on my humble experience, and not prescriptive in any way! Feel free to discard those that don't feel relevant to you. And I'll be happy about any feedback about your own experience.

A tentative typology

Before detailing how to write a blog post, one should first accept it depends on the type of post. On this blog, I've noticed my posts can be mainly put into one of those categories:

1. Solving a problem
2. Learning in a step-by-step way
3. Comparing alternatives
4. Reviewing a book
5. Ranting!

Remember that all models are wrong, but some are helpful. While this typology is helpful, it might not be so clear-cut in every case. Also, there are a lot of other blog post types, but those listed are the ones that regularly worked for me. Let's detail each of them in turn.

Solving a problem

I started this blog when I was working as a consultant: my day-to-day job was basically to solve problems. The idea behind this kind of blog post is to make use of one's work during one's job. It also allows to deepen the understanding that one was not able to get due to time's constraints during the project.

In this kind of post, the author should take utmost caution to remove any information that shouldn't be made public. I'd very strongly advise that the post be proof-read by others before being published.

Writing such a post should be structured around the following sections.

1. The context

   When reviewing other's blog posts, this is the part that is the least detailed, when it's not forgotten altogether. IMHO, it should be the most important one. Engineering is all about trade-offs. If the context is not described in detail, the rest of the post loses a lot of value.

2. Considered alternatives

   Before choosing a specific solution, the team probably considered multiple alternatives. They should be listed with their pros and cons in regard to the context described in the previous section. Try to be as objective as possible.

3. Chosen solution

   Now is time to describe the chosen solution, along with its pros and cons. More importantly, this section should tell why it was chosen, again in regard to the context.

   Remember that not everything is related to technical issues. In some cases, the reason bedind the choice might be because of the organization, the schedule, conflict between team members, etc. Those are perfectly valid reasons. If you feel comfortable - and you're not covered by a NDA, feel free to say so. If not, tell explicitly you're not at liberty to say why.

   The important bit to remember is to strive to be as transparent as possible in regard to the project.

4. Conclusion

   This section recaps the above in a few sentences. With hindsight, tell whether the chosen solution was the right one. If no, explain the reasons why, and why others shouldn't take the same decision in the same context. Make the conclusion your own retrospective.

Examples:

• What's the version of my Jekyll site?
• Logging additional metadata

Learning step-by-step

In this kind of post, the writing itself is secondary. The important bit is the learning part. I personally use it when I want to learn about a specific subject. Writing is then quite easy, because things learned are still fresh in my mind.

The blog post's structure depends a lot on the subject itself. In general, one should design a section per step in the learning process. It's perfectly fine, even recommended, to write about steps that ended in dead ends. Remember that one's dead end might be somebody else's open door.

Examples:

• Your own Kubernetes controller - Laying out the work
• Your own Kubernetes controller - Developing in Java
• Your own Kubernetes controller - Improving and deploying

Comparison of alternatives

This kind of post tries to help readers make an informed choice about some alternatives. The idea is to have a set of alternatives, as well as a set of criteria. An important part of the work is to find the relevant criteria: while it's not feasible to be exhaustive, one should mention the major ones. Here's a proposal about such a post's structure.

1. Evaluation of alternatives

   Each section should be dedicated to a single criterion. Each alternative should be evaluated regarding this criterion in one, or a couple of paragraphs.

2. Recap matrix

   The most important section should be a recap matrix of all alternative/criterion combination. It's advised to make use of colored symbols.

3. Optional conclusion

   To help readers, one can write a conclusion. It should flesh out a few contexts, and extrapolate the "best" alternative given the above matrix.

Examples:

• Comparing Lombok and Kotlin
• Git service providers comparison

Book review

The name says it all: read a book, and write a review about it. Note that the reading part is actually the most time-consuming part of the blog post. It's a great way to take notes, and let others benefit from it at the same time.

While I've done a couple of book reviews in the past, I'm not sure I got them right. This is the way I did it, only time can tell if I continue doing them this way - or not. In the meantime, here's the structure that I used before.

1. Facts

   • State the number of pages, of chapters, the price, etc.
   • Sum-up the whole book into a paragraph i.e. what's the book about
   • Describe who the book is intended for

2. Pros

   State one thing you like, one paragraph for each

3. Cons

   State one thing you dislike, one paragraph for each

4. Conclusion

   This section is where you can be less objective, writing your personal feelings about what you read. The final sentence should be whether readers should acquire the book, or not.

For teams, there's an alternative type of book reviews that I've successfully lead in the past: "What our team read". Each participating team member writes a short paragraph about one of the last books he liked.

Examples:

• The Leprechauns of Software Engineering
• Specification by Example review

Opinion rant

Again, the name is pretty descriptive. The structure depends a lot on the subject.

The important bit in this kind of post is the choice of the subject:

• The focus should be on an unpopular opinion. Howling with the wolves is pretty useless, both for you and readers.
• You should be 100% convinced that you're right despite not belonging to the majority
• Last but not least, there should be enough arguments to support your position

Example: There's no such thing as CI/CD!

Other considerations

• Code repository

  I assume most blog posts will be about code and programming. Hence, it makes sense to provide code along them. There are two cases:

  • The post is based on a full-fledged code repository. You can copy-paste code snippets in the relevant parts of the blog post. Also, don't forget to link to the code repository. GitHub has a bit of an advantage here over GitLab: in the repository description, link back to the blog post.
  • If a code repository is not warranted, but code snippets are necessary, they should be tested in the IDE to make work as expected.

• Series

  I've experienced an interesting fact: the longer a blog post is, the more chances I'll skip reading it after some point. There's a relationship between the content's quality and the content's size I'm willing to go through.

  But in all cases, if the post is too long, I will stop reading. I unfortunately cannot state a rule concerning the "right" size, it's a matter of gut feeling for me. In all cases, I'd recommend splitting posts that feel too long into separate parts and create a serie.

• Reuse

  Writing a blog post is a significant time investment. Why not get more out of this investment by turning it into a talk? While not all blog posts can be turned into talks, some do. In that case, preparing the talk will be quite easy.

Remember that all this post is very empirical, so take the above advices with a pinch of salt. Also, please feel free to give your own advices in the comments, I'll be happy to learn about upping my game myself.

Originally published at A Java Geek on August 9^th, 2020