How to Write About Software
On Oct 4, 2024, I gave a talk at SquiggleConf about how software engineers can write great technical blog posts.
Recording
I’ll post the recording here when it’s out!
Feedback
This was my first time speaking at a conference, and I was very encouraged by the feedback. Thanks everyone for your support!
Extended Q&A
There were more questions in the Discord channel than we could cover during live Q&A. So here are my full answers.
My Taste
What is your favorite book about writing?
[Answered at live Q&A.] It’s impossible to name a favorite—there are different flavors of great! But one book I think is underrated is A Writer’s Coach by Jack Hart (Goodreads). In the Table of Contents, you see chapters like “Rhythm,” “Color,” and “Force.” The book is written for journalists, but you can apply its lessons to other nonfiction.
What company’s technical blog do you respect the most? (Outside of Render!)
[Answered at live Q&A.] The first one that comes to mind is Stripe’s Engineering Blog, because everything they publish is so high quality. You know whatever you read will be worth your time.
I worked at Stripe as a software engineer, and even the writing in internal design docs was high quality.
On the other hand, aiming for Stripe’s level of polish comes with tradeoffs: you will publish less. Dan Luu has a post about this. For most people and startups, I think it’s better to lean towards reducing friction in your review process. (Of course, a big hack is when your editor is an engineer, and can also comment on content, not just style and organization.)
Many “great” blog posts are not polished.
What is your favorite technical blog post of all time (that you can think of)?
I have a hard time answering this, because I tend to look at “how well did the author achieve what they set out to do?”—and people can hit high marks with very different-looking outputs.
For example, keeping with the PostgreSQL theme in my talk, here are some examples:
Everyday Great: Don’t Believe the Big Database Hype, Stonebraker Warns
Great Great: Herding elephants: Lessons learned from sharding Postgres at Notion
Work
How do you handle going editor mode on a coworker without offending them?
[Answered at live Q&A.] I have a rule: I won’t edit a coworker’s piece until I’ve talked to them in person first. Writing can feel very personal, so if we’re working together, I want to get to know you first.
How do you tell a developer that their topic idea is not worth publishing?
This is easier than it sounds! If we’ve talked about your “wins,” it’s easy to then suggest other topics that can better achieve your goals. (What’s hard is when you’re still figuring out your goals—but I find this a fascinating puzzle too.)
How do you write about work without revealing too much internal data/code that may not be ideal to share outside your company?
There are two good times to check for this: before you start writing (“Will this topic by itself be a problem?”), and after you have a draft.
Obvious topics to avoid are:
products that aren’t yet public
information that gives malicious users a strong advantage, and
details that make the company look like a clown
As an engineer, you likely have a good sense already. If you’re worried, talk to a few other colleagues you think have good judgment, and ask your security team for a review.
Getting Started
Do you recommend building your own blog vs. using a platform like Hashnode?
I recommend using whatever gets you publishing earlier. That’s probably a blogging platform. Blogging platforms also often implement basic SEO best practices for you, if you care about that!
How do you recommend getting started and gaining traction with technical writing and/or blog posts?
Find someone (it could be a person on the internet you don’t know) who has a meaty question, answer it through writing, and share it with them! You’ll get feedback.
Measuring Success
How do you measure quality beyond subjective intuition? Views are an obvious first order metric but does Render track anything else? Also, thoughts on the DigitalOcean-style $100 for a decent post content strategy?
I’m not sure it’s possible to measure quality “objectively.” The can get closer by creating and rating ourselves against frameworks, like the ones you saw in my talk, like the 4 types of tech blog posts, what makes a piece “Great”, and the ingredients of “Great.”
At Render, we do pay attention to qualitative feedback, such as the feedback from the eng candidate you saw in my talk, plus things like newsletter placements and tweets by readers.
The DigitalOcean-style “decent post” can still be valuable to a company to fill obvious information gaps. However, gen AI will likely make these less effective than they used to be.
Writing & Formatting
When is a paragraph better than bullet points?
[Answered at live Q&A.] Bullet points make sense when you’re talking about a list of things. Most paragraphs aren’t lists of things.
I saw in one of your examples that the before code blocks were light mode and in the after, the blocks were dark mode. Was that design change intentional?
The honest answer is: what you saw was a style difference between GitHub and Render. But that’s not the fun answer:
