The Container Solutions Opinionated Guide to Blogging

Blogging is one of the central activities at Container Solutions. We try to regularly publish blogs on a variety of topics, from technical pieces to articles on strategy or psychology. Personally, I’ve been blogging for at least a decade and would like to think I’ve learnt a few lessons on what works and what doesn’t. As everything is moving online at the minute, this seems a great chance to share my tips with everyone.

This guide contains advice not just on how to write a blog, but also what to write on and what to do to promote blogs after they are published. This is an opinionated guide I developed for internal use at Container Solutions, and I'm sure people will disagree with parts of it. That’s fine— one of the most important skills in blogging is to develop your own voice and style, which will likely mean adapting the advice before.

Why Write a Blog?

Blogging is a rewarding activity for which people have a diverse range of motivations. Some of the most common/important are:

• To ‘give back’ to the community. If you’ve just solved a thorny problem or spent time investigating an under-documented aspect of something, it’s a great idea to write a blog on it. This makes everything easier for the next person, who can now use your work as a starting point. Try to write the article you wish you’d read before you tackled the problem. Slowly building on knowledge is how science and society progresses.
• To create an audience. If you regularly publish quality content, people will keep coming back to your site. This can be helpful in the future—if you’re publishing a new app or looking for a new job, you know that by posting it on your site you are guaranteed that some people will see it. And if they trust you from previous work, they are much more likely to want to help or believe in what you’re doing.
• To clarify your thoughts on a topic and improve your communication skills. If you write an introductory article on different types of lifting devices, it forces you to both make sure you have a strong overview of the mechanical options, and that you’re able to convey that information to someone that doesn’t know jack(s) (sorry).

Before You Start

So now that you’ve decided it’s worthwhile writing a blog, where should you start? If several people in your organisation are working on blogs, first make sure you coordinate with them. This will help avoid multiple people working on overlapping blogs or on topics that are already well covered. One big advantage I have at Container Solutions is that we employ our own editorial staff to help with editing and copywriting. This team makes sure that our blogs are clearly written and up-to-scratch, but also helps us decide on what to write about in the first place.

Selecting a Topic 

The best thing to write about is the thing you just did. It is fresh in your mind, so writing should be fast and easy. The second best thing to write on is the thing that you've been thinking about in the shower and on the commute to work (err, assuming that's something work related). The third best thing is to choose a topic you're interested in, research it, and write something up.

‘Best’ here is based on time—the longer it takes to write a blog, the less time you have for other stuff and the more likely you are to become bored and give up, or produce poorer quality work.

However, I absolutely do not mean you shouldn't write a blog if no topics spring to mind. At Container Solutions, we keep a list of topics that we want to create blog posts about, but if you don’t work here, there are a thousand places to find inspiration. Have a look around at what other people are writing about and see where your thoughts take you. With any luck, something will spark your interest and you'll find it naturally promotes itself to ‘the thing you think about in the shower’. Write about that.

There are a bunch of excuses people use to avoid writing blogs and most of them are mistaken:

• ‘Someone has done it better already’. Yeah, they probably have. But you can still link to that article and provide your own spin on it (do not plagiarise). Or you can start from scratch and come up with something that's entirely your own take. For example, there are hundreds of ‘getting started with X’ articles, and there will always be a place for one more.
• ‘No one will be interested in my opinion’. Yeah, maybe. You're (probably) not Kelsey Hightower. But no one will ever value your opinion if you don't share it. I'm an idiot and occasionally people still listen to what I say—you're reading this, after all.
• ‘My English isn't good enough’. A lot of people at Container Solutions—and in tech in general—have English as a second language. For people with less experience in English, it is a harder, longer process to write a blog. My advice is to ask a native English speaker to read what you write and give you feedback . Like it or not, being able to communicate well in written English is an essential part to career development in tech. If anything this excuse is an argument for writing a blog, in order to improve your skills.

Types of Blog Posts

There are lots of different types of blog posts, and, in my opinion, they're not all equal:

• Top X lists. Most people are a sucker for these and they can be quite easy to do. The main problem is that they can be seen as ‘click-baity’. Personally, I say go for it, as long as such posts don't start to dominate your output.
• Event reviews. Be careful with this one. Conference reports age quickly and tend to have a small audience (why would you read a conference report?). Instead I would recommend writing about a talk or theme in a conference; was there a presentation you particularly liked? Summarise it, link to the video or talk, and add your own thoughts, plus further reading. The title of the blog will then be the topic in question, which will continue to be relevant long after people have forgotten about KubeCryptoOps 2020.
• Predictions. These can be fun, but only if the predictions are controversial or risky. I think these only really work if you have an audience already or come from a position of authority. Like event reviews, they don’t age well.
• How-to's. Blog posts that tell you how to do something, fix something, or get started with something are probably the most valuable to the audience,  in my opinion. They are genuinely helpful to people (you will often get thanks on social media or comments for saving people time) and can generate a lot of traffic if promoted properly. With proper use of keywords, they can become a recurring source of traffic (my editor commented ‘Google loves anything that answers a question’). Note that a how-to doesn't need to be long; if you can tell someone how to fix a common Docker issue in a few lines, do it!
• Case studies and announcements. Articles on things you've done, etc. This can be essential to marketing and brand awareness. It's great when we have articles on our hackathons or successful engagements with companies. Case studies are normally in-depth pieces on particular engagements with companies. These can require approval from outside parties (like clients) and can be a lot of work, but are very valuable pieces of content.
• Opinion pieces. If you have a strong opinion on a topic, especially a controversial opinion, you can generate a lot of traffic. This is the kind of stuff that does the rounds on Twitter and Hacker News, etc. However, they are also likely to sink without trace. Be aware that they are likely to generate push back and negative comments, especially if you're a little clumsy in your argument or get some of the facts wrong (make sure you double-check your facts and run your work past a trusted voice before publishing).
  As an example, some people got a bit annoyed with my Programming Languages for Microservices blog, and in retrospect I wish I'd been a little more careful not to knock JVM-based languages. In short: be brave and controversial, but be prepared for negative comments and take it all with a pinch of salt.

Or to give simpler advice, I'd recommend leaning towards writing ‘How-Tos’.

If you're smart, you can merge categories. For example, Ian Miell has had a lot of success on his blog with ‘Things I learned about X’ and ‘X Things I wish I knew about Y’  posts, which is arguably a how-to merged with a list article.

Writing the Blog

So you've decided what you want to write about. Now comes the hard bit.

The most important advice I can give you is:

• Have a plan: decide how you will structure your blog in advance. Create an outline; write the section headers first, then go back and fill them in.
• The introduction is the most important part of the blog. It's here you need to pull the reader in so they will keep reading. For this reason, it's worth spending a disproportionate amount of time on the first couple of paragraphs.
• Remember the reader. By far the biggest problem I see in blogs is where the writer forgets the reader. For example, the writer starts using advanced terminology in an introductory article. It sounds obvious, but it's an easy mistake to make, as it's hard to remember what we didn't know.
  We have to make some assumptions of our reader based on the fact they're reading it (a reader must have some interest and background knowledge of Kubernetes before they click on ‘Kubernetes Failure Stories’, for example), but getting the level correct is difficult. 
  The common advice is to write for a specific person. For example, imagine that you are explaining Istio to someone without much knowledge of it (like, say, our CEO). How would you do it? It can also be worthwhile to mention the level of knowledge required or assumptions in the opening paragraph.
  Whilst writing, keep asking yourself what your reader would want to get out of this; at the end, ask yourself what they have learned. Read your blog post back through and consider what questions they would ask and where they would get confused.
• Revise. I often write in a ‘brain dump’ style to get something out of my head. But after that, I find it's important to go back and re-organise and revise the language in order to clearly express my thoughts. One way to check the clarity of your post is to try to sum up the theme of your blog post in one sentence (for example: ‘Many IT team members are not equally experienced in Cloud Native technology, but here is our method of helping to close those knowledge gaps’.") If you can't do it, you may need to think harder or talk to your editor about what you want to communicate in your article.

After that, I have some more minor suggestions:

• Try printing out your blog post and reading it back. You'll be surprised at the number of problems you find when you change mediums; it seems to reset your mind or something. A similar technique is just to leave a post for a day before reading it back (thanks to Ian Miell for this suggestion).
• This should go without saying, but don't plagiarise and always cite your sources. If you were heavily inspired by a book, talk or blog, say so and link to it. It's OK to pull quotes out of something, but you need to make it clear that's what you're doing.
• Add links to terms and concepts that the reader might not have encountered before. Also consider adding ‘further reading’ links to relevant content.

Other than that, I would refer you to other sources that have written much more eloquently on technical writing than I have. Notes on Technical Writing is a good resource that was shared recently on Hacker News. In particular, pay attention to the resources at the bottom, which include Tips on Writing a Great Science Paper by (the great) Cormac McCarthy and On Writing Well by William Zinsser.

Choosing a Title

The title and first paragraph are of utmost importance with regard to search. If your blog is about Docker and Kubernetes on an Atari ST, get those keywords into the title! Do not use something generic like ‘Computing on Retro Hardware’. Think about what people are going to search for and what keywords they will use if they want to find the info in your blog. Using more specific keywords is generally better; there is less competition and you will be able to rank higher.

A good example from the Container Solutions blog is Lian Li's Using Google Container Registry with Kubernetes. The article title is what people type into Google when they can't get GCR to work, and for that reason became a well-performing blog (in terms of monthly readers).

Getting and Handling Feedback

This is hopefully straightforward, but be mindful of soliciting too much feedback; it can be a burden which really slows down the process and potentially dilutes the author’s voice.

For most posts, it's probably best to send to one or two people whose judgment you trust. If there are specific aspects you want feedback on, let them know (for example if it's a technical blog, you might ask a knowledgeable friend or colleague to double-check the technical details). 

People are surprisingly different in the quantity and quality of feedback they provide. Some people are more critical than others (and I think everyone at Container Solutions knows where I am on that spectrum!), but please take all criticism with a huge grain of salt. Just by writing and putting yourself out there, you've done a big thing. 

If you disagree with some feedback, it can be difficult to decide what to do. If it's a fairly minor point, it's probably enough to explain that you disagree and intend to leave the suggestion as is. If it's something more important or the other party believes it to be more important, it’s worth discussing further or seeking a third opinion.

Make sure you budget a reasonable amount of time for edits. Most people think ‘I'm done’ when they finish the first draft, but there is still a long way to go.

Promoting Blogs and Following Up

We’d all like it if, once we’d written a blog post, thousands of readers would show up automatically and shower us with praise. Unfortunately, that’s not the way it works. At least not in my experience. Instead, you need to do some work.

What can drive a lot of readers and community involvement is submitting to news aggregators and similar sites. Suggested sites to submit to:

• Reddit. This is probably the most important one. Choose a subreddit that is appropriate and put a link to your article here. If the subreddit doesn't allow posting URLs, you will need to write a short description and link to it in the body.
• Hacker News. Everyone wants to get on Hacker News. If you manage it, you will suddenly get a flood (tsunami) of traffic. It's a hard thing to manage however. There are mechanisms to identify ‘voting rings’ and other ‘fraudulent’ behaviour. It's probably not worth your time trying to 'game' it.

There are other places to consider, like Lobste.rs (if you're a member) and Slashdot.

Once you’ve submitted, monitor the site for comments and questions, and answer them where possible. Walk away if people are getting argumentative and don't take criticism personally (yes, easier said than done).

Syndication

By syndication, I mean posting your blog on third-party sites. This can be a powerful tool for building an audience and increasing the Domain Authority of your site.

Stats

Don't be discouraged if you don't get a lot of hits. The majority of my blogs get a low number of readers. The best way to increase numbers is to keep trying with new material. Follow the advice in the previous sections.

How many hits is a lot? It's hard to say. If you manage to get upvoted on an aggregation site, you will likely get between 100-10,000 hits (possibly more!) in the space of a few hours or days. For a personal blog, I would generally consider any post with more than a dozen or so hits a success.

One of the most interesting things is that several Container Solutions articles get large (and growing) numbers of repeat visitors month after month, rather than getting a large number of initial visits and then ramping down. These are sometimes called ‘compounding articles’  (thanks Frank Scholten). All of these articles are 'How-Tos' and either explain how to use something or fix something. In some cases, the blogs didn't get much traffic at the start, but have done well with search keywords in the long term.

Taking It Further

If you have a blog that does well, consider doing a follow-up, or doing a talk on the same subject. Chances are you've hit on a topic of general interest and you should capitalise on the opportunity.

Conclusion

At Container Solutions, we put a lot of effort and money into blogs. We believe that this is a great way to contribute back to the community and also to spread awareness of our company and the work we do. Hopefully some of the advice in this article will prove helpful to you and help you build your own audience. Please let us know if you have any questions or feedback on this article.

Photo by Andrew Neel on Unsplash