Yesterday, I published a rather long post about the way that SQLAlchemy uses database transactions. This was one of the most difficult things I’ve written about, not so much because of the subject matter, but because I couldn’t figure out when to stop writing. In the end it took two and a half months to finish, mostly because it was intimidating as heck. Today I want to unpack why I was afraid of it a little.
How to Shave a Yak, vs. Why to Shave a Yak
A major part of the difficulty finishing that post was that I wanted to keep explaining why I was writing about this rather niche problem. I think there’s a spectrum between saying “Hi everyone! Today we’re going to talk about how to shave a yak”1 and doing the whole
I’m way more on the record scratch side of the spectrum. I think I really enjoy telling stories about the reason why things are the way things are.
Keep your projects scoped small
2019 has been a year or realising that I need to keep projects scoped super small if I’ve ever got any hope of shipping them. It applies to writing, to work, to building bottle lamps, to fixing cameras, to building habits, to wading through German bureaucracy (einen Besenstrich nach dem anderen).
Ruthlessly scoping your work down to the smallest possible kernel of truth is the thing that allows you to get it done and out into the world. Sometimes, that’s easy! Usually when you’ve been mulling an idea over for months. Other times, you could sit down and write 10,000 words on a topic in a day. Then, you’ll spend a week simmering it down to 2,000 words that people will actually want to read.
Choosing an audience
Something else I ran into on this project is – choosing an audience is really difficult. Am I writing for Database Sorceresses / Sorcerers who are able to conjure Perfectly Normalised Data from the earth itself, or am I writing for recent bootcamp graduates, who haven’t had as much exposure?
Fabian performs Database Wizardry, 2019, pixels on <canvas />
My intuition is that the two ends of the spectrum require really different writing styles and different levels of context. So being precise about exactly who you’re writing for is important.
Cooking blogs
I feel like I’m stumbling into the “cooking blog” paradox here. I don’t care whether “glazed carrots remind you of a warm hug on a cold day”, I just want to know if I should caramelise the sugar before adding the carrots. But presumably all that stuff is written for something? Someone? It’s unclear to me whether food bloggers write this because they’re “optimising” their content for search engines, because they feel like it’s wrong to just jump into a recipe without any context, because they like telling stories, or because it’s what their readers want. It’s interesting to me how different your intent is when you’re coming from Google vs subscribed to a newsletter though. The former is more interested in the facts and the how-to. The latter is probably more into the why.
Imposter Syndrome
If I’m being truly honest with myself, I think a significant source of tension in finishing that post is a deeply internalised imposter syndrome – the tiny voice saying “I have to sound smart when blogging about Technical Things” – which is conducive to explaining all of your reasoning all the time.
This is a deeply silly reason – it’s motivated by the fear of being judged an idiot by an Internet Stranger. I guess I’m inclined to chalk this up to the fact that impostor syndrome is hard to shake and everyone suffers from it. I thought I’d cured mine a couple years back, but evidently it’s something to be aware of whenever trying something new, like blogging about deeply technical content. 🌈
Writing for people you care about
In the end, I think what got me over the line was that I decided to write for people I knew rather than an abstract concept of an “audience”. Writing for my team – Stefan and Sarah and Zahid and Mike – was a very different experience than writing for a hypothetical internet person and their hypothetical needs and ego. A bonus is – these are people I feel safe with, so I felt less like I needed to explain the entire world or justify anything.