Engineering · 3 min read
Writing blogs as an engineer
You just solved something hard and interesting. Writing it up is worth more than you think, both to the people who'll read it and to you. Here's how.
We build in the open, and writing about the work is part of that. When an engineer here writes up something they figured out, it does a surprising amount at once: it helps someone stuck on the same problem, it brings us users and future colleagues who like how we think, and it becomes the reference the next person on our own team reaches for. The blog is open to you. You don't need permission to start writing, and you don't need to be a "writer."
What's worth writing about
The audience is people like you: engineers at growing companies, hitting the kind of problems you hit. Two questions tell you if a topic is worth a post:
- Would you send this to an engineer friend as "oh, you'll find this interesting"?
- Would it have saved you time or taught you something two years ago?
If either is a yes, write it. The most common mistake is assuming your thing is too obvious to bother with. It almost never is. The specific problem you just chased down, with the real numbers and the wrong turns you took, is exactly the post nobody else can write, because they didn't live it.
You underrate your own experience
The stuff that feels routine to you, the migration you just survived, the bug that took three days, the tradeoff you agonized over, is precisely the stuff other engineers are searching for and can't find written down honestly.
How to write one
A structure that reliably works:
- Hook: the surprising result or the pain, up top. Earn the next paragraph.
- Context: just enough background for a stranger to follow, no more.
- The journey: what you tried, what failed, what worked, and what you'd tell your past self. The failures are the interesting part; don't tidy them out.
- Resolution: the specific change, the actual numbers, a chart or a screenshot if it helps.
Write it the way you'd write a good Slack message, an email to a colleague, or an internal RFC: plain and direct, in our voice and the habits from how we write. Don't reach for a corporate register you'd never use in person. Name your sections for what's in them, not "Background" and "Conclusion."
On AI: use it to research, to outline, to sharpen a rough draft. Don't have it write the whole thing. Readers can feel a post that no human really wrote, and they discount it instantly, which defeats the entire point of putting your name on it.
Getting it published
The mechanics are the same as any other change, because a post is just an .mdx file in content/blog:
- Float the idea if you want early eyes, but you don't have to.
- Open a draft pull request with the post in
content/blog. - Ask for an editorial review. Expect a round or two of notes; that's the process working, not a verdict on you.
- Merge, and it publishes.
Then, the uncomfortable but necessary part: share it. Post it where the people who'd care will see it. It feels like bragging and it isn't; a post nobody reads helped nobody, and the writing was the hard part, not the sharing. This is the last mile of building in the open, and it's the same standard we hold docs to: if it was worth making, it's worth someone actually finding.