How Engineers Can Write Great Blogs | Bolt Recommendations

Writing is an extraordinarily influential form of communication. By consistently producing professional content, many engineers and entrepreneurs have built significant influence and credibility in their respective fields.

Robin Moffatt is a well-known American expert in data engineering and stream processing. He is highly active in technical communities, sharing his knowledge and experience through blogs, talks, training, and other formats — widely recognized for his deep understanding of complex technical concepts and his ability to explain them clearly.

Recently, he shared his writing methodology on his blog, along with numerous writing tools and learning resources. We have organized and translated his article, hoping to offer some food for thought. The original text can be accessed via the "read more" link.

01 Why We Write

First, I enjoy sharing information. This might be a new tool or technology I've learned, some tricks I've discovered, or sometimes venturing away from tech entirely into life reflections and introspection. On this blog, I write to share ideas that interest me. I could jot down notes and reply directly to the person who originally asked, but if it's useful to them, it's hopefully useful to others too — making it worth writing up and publishing.

My second reason for writing is to learn for myself. You can wing it when giving a presentation, but actually writing something down — committing bytes to disk and explaining it clearly — is different. I often find gaps or weaknesses in my knowledge that I need to explore before I can write about them. That's why I write.

Beyond that, writing has other pleasant "side effects": anything public (your blog, documentation for an open-source project, etc.) helps build your credibility in a field and makes others aware you exist.

02 How Engineers Write

1. Lecture: The Craft of Writing Effectively

Before diving in, I recommend checking out a lecture called The Craft of Writing Effectively. It's led by Larry McEnerney, Director of the University of Chicago Writing Program, who has strong opinions about writing. His observations about academic communication have direct parallels to how developers communicate with each other.

I'd seen this lecture recommended multiple times but kept putting it off due to its length. I wish I hadn't hesitated — it's genuinely excellent.

🎬 Video link: https://www.youtube.com/watch?v=vtIzMaLkCaM

2. How do I write as a software engineer?

Every writer has their own approach, which also varies depending on audience and purpose. A report published in an academic journal has a different structure than a playful tweet. A developer-facing blog differs greatly from in-depth product manual documentation. Every medium and audience is valid; the key is ensuring your writing matches it.

My motivation for writing usually stems from something catching my interest. It could be new technology, a deep explanation, a random life reflection, or anything else. Typically I ask myself a few questions: Would I want to read what I'm writing? Does it avoid the boring and tedious?

There are three key dimensions worth considering here:

• Clarity
• Personality
• Consistency of content

These dimensions roughly cover the various materials we might write:

Things aren't always that simple, especially for certain platforms where the range is quite broad:

What do these different dimensions mean in practice? Let's explore.

2.1 Clarity is key

Of these three dimensions, the first is fairly straightforward and shouldn't really vary. Whatever you write, whoever you write for, it must be clear. Writing clearly encompasses everything from sentence structure and paragraph breaks to overall article architecture. This can be surprisingly difficult, but it's essential if you want to produce material people will actually read.

One neat trick about clarity: remember that what you omit matters as much as what you keep. This will be highly context-dependent. Documentation is by definition comprehensive. A blog might want to get to the point faster, offering links to background material for readers who need it. As the saying goes, less is more.

Some types of writing may allow more personality than others, but all writing can at least potentially be accessible and clear. For example, just because you're writing documentation doesn't mean you can copy-paste all the generic, convoluted content from requirement docs. Write documentation you'd want to read as a developer. It can be complex and precise while still remaining accessible.

2.2 Personal writing style

Should writing style show through in your work?

How you position your writing style depends on your preferences, audience, and subject matter. If you spend time on Twitter, you'll notice infosec posts differ from DevOps posts, which differ from data engineering posts. Each has its own microculture and conventions, and the degree to which an author's style shines through varies.

Generally, you'll find that generic writing mediums like company project reports or product documentation call for a neutral voice. This doesn't mean boring — it means a certain consistency. In a project report, information shouldn't be obscured by colloquialisms. Imagine the cognitive dissonance if a documentation set were written by multiple authors, each trying to stamp their personality on every page.

When we turn to blogs and other types of writing, we deliberately want to include some personal flavor. How much is for you to calibrate with your audience and yourself. There's a relatively sweet spot: you express enough personality and authentic voice without compromising the readability of the content itself.

2.3 Consistency and standardization

This is strongly related to personality and perspective, but more concerned with the structure and content of the material.

Take blogs as an example. You'll find that company or project blogs place heavy emphasis on consistency of information and structure, typically featuring thorough introductions and background, and being comprehensive. By contrast, a personal blog might sometimes be nothing more than a developer wanting to document bug information and solutions for their own future reference. They might expand it into a longer article — this isn't necessary, but it still holds value.

03 Blog Writing Template

I have a structure I use frequently, which I also employ in many conference talks. It goes like this:

• Tell them what you're going to tell them
• Tell them
• Tell them what you told them

In practice, this structure looks like the following:

1. Article introduction

At the beginning, the core task is telling readers what you're writing about and why they should care. The opening might be a brief explanation of why readers would find it interesting, or why they should read your take on it. The key is establishing connection with your audience here. Not everyone wants to read everything you write, and that's okay.

At this stage, you need to give people the right to self-select. For example, if you're writing about data engineering, you can explicitly tell application developers they should move along — there's nothing to see here.

2. The content itself

3. Summary and recap

At the end, make sure you don't simply close with "End." The conclusion can summarize what you've just discussed and give people directions for further exploration. Code examples they can run or inspect, new services to sign up for, videos to watch, or simply a life reflection to ponder.

04 Start Writing

If there's only one piece of advice for improving your writing, it's this: start writing. I don't mean go write an article. I mean start writing something, anything. Some notes, some fragments, some complete paragraphs. It might even look like this:

As you write more, stories and threads begin to emerge. Initially one section, later perhaps two, as you realize there are different elements to dissect.

Iterate, iterate, and iterate again.

I've recently found that using a Pomodoro timer is an effective way to maintain focus and take breaks. Rather than staring at the screen in despair as your article stalls, spend a dedicated period then step away. Maybe you come back after the break, maybe you wait longer. Like many problems in life, things resolve themselves over time.

05 Find a Good Editor

A good editor understands what you're saying and helps you refine and shape it into better form. They respect the expression in your writing while improving clarity and grammatical accuracy.

06 What to Write and What Not to Write

6.1 What to write

We've discussed the "why" and "how," so now let's talk about what to write. What to write usually comes from questions you pose yourself — if it's interesting to me, I'll write about it. But let's assume your creative inspiration isn't flowing, yet you still really want to publish a blog. An excellent source of writing inspiration is social media content: StackOverflow, Twitter, Slack, Discord. Along the way, observe the following:

• What questions do people keep asking?
• What counter-patterns and misconceptions do you see?
• What are the new trends?
• What cool things can you do with xxx?

6.2 What not to write

What not to write depends heavily on personal preference. I have zero interest in growth-driven blog styles. You know the type: listicles, SEO bait, and so on. It's cheap, developers see right through it, and it damages the blogger's credibility. That said, if you've written a good blog, it's worth sharing. Writing should be valuable — not just to yourself, but to readers. Writing isn't about filling pages; it's about conveying interesting and useful information.

07 In Summary

To summarize, remember that these two statements are not mutually exclusive:

1. Write for yourself — identify what interests you, then write about it.

2. Think about your readers and what value you're providing them through your writing.

08 Tool Stack

Everyone has their own preferences for blog writing tools, but here's my stack:

• Obsidian for drafting
• CleanShot X for screenshots and annotations
• Grammarly for proofreading (for your readers' sake, please proofread seriously. Nobody wants to read a poorly written blog)
• Hugo and GitHub Pages for publishing and hosting

09 Learning Resources

Gareth Dwyer (software engineer, writer, and technical consultant) provided a valuable list of learning resources:

1. Blogging for Devs course: https://bloggingfordevs.com/
2. Antonio Cangiano's blog post: https://pragprog.com/titles/actb2/technical-blogging-second-edition/
3. Sophie Watson's excellent talk: https://www.youtube.com/watch?v=kOnZovTFTHc
4. Dmitry Kudryavtsev's blog post: https://yieldcode.blog/post/why-engineers-should-write/
5. Google Technical Writing course: https://developers.google.com/tech-writing

📮 Further Reading

Linear Bolt Bolt is an investment initiative by Linear Capital specifically designed for early-stage, global-market-facing AI applications. It upholds Linear's investment philosophy, focusing on projects driven by technological transformation, with the goal of helping founders find the shortest path to their objectives. Whether in speed of action or investment approach, Bolt's commitment is lighter, faster, and more flexible. In the first half of 2024, Bolt invested in seven AI application projects including Final Round, Xinguang, Cathoven, Xbuddy, and Midreal.