Notes

I have just released a guide on leaving Germany.

A few things I’ve enjoyed reading recently.

Miscellaneous:

• RMS Carpathia’s rescue of Titanic survivors (hopemaxxing)
• Finding Peter Putnam
• How to Fix a Typewriter and your Life
• The truth behind the 2026 J.P. Morgan Healthcare Conference (humour)
• How I Taught My Neighbor to Keep the Volume Down (humour)
• The Stranding of the MV Shokalskiy
• An Interactive Guide to Ambiguous Grammar (2015)

Life:

• Thank you for being annoying
• How to be less awkward
• The thirteen laws of good luck
• Maybe you’re not actually trying
• Are you stuck in movie logic?

Technology:

• Kind software, which reminded me of calm technology
• How Google Maps quietly allocates survival across London’s restaurants
• AI: Markets for Lemons, and the Great Logging Off (2022)
• To those who fired or didn’t hire tech writers because of AI

I write documentation for a living. Although my output is writing, my job is observing, listening and understanding. I can only write well because I have an intimate understanding of my readers’ problems, anxieties and confusion. This decides what I write about, and how to write about it. This sort of curation can only come from a thinking, feeling human being.

I revise my local public transit guide every time I use a foreign public transit system. I improve my writing by walking in my readers’ shoes and feeling their confusion. Empathy is the engine that powers my work.

Most of my information is carefully collected from a network of people I have a good relationship with, and from a large and trusting audience. It took me years to build the infrastructure to surface useful information. AI can only report what someone was bothered to write down, but I actually go out in the real world and ask questions.

I have built tools to collect people’s experience at the immigration office. I have had many conversations with lawyers and other experts. I have interviewed hundreds of my readers. I have put a lot of information on the internet for the first time. AI writing is only as good as the data it feeds on. I hunt for my own data.

People who think that AI can do the work technical writers have an almost insulting understanding of the jobs they are trying to replace.

It’s that time of the year where I sit down and seriously think about my resolutions for the next year. I take those seriously.

This time, I think a lot of Swizec’s recent visualisation of a drunkard’s walk. If he takes each step in a random direction, he will never stumble further than the square root of the number of steps.

But if you bias his steps 10% in a given direction, look at him go!

This is how I see new year resolutions, less as an oath, but as a 10% bias in some direction.

Some articles I have enjoyed reading recently:

• I want you to understand Chicago
• The art of the aperitivo and of the sprezzatura
• Permission to be wrong about what you want
• The Company Man
• Thank you. Fuck you.
• Common plots of economic history
• Eggstatic fortress
• We will not cancel us

Some problems are like getting a diploma: you work at it for a while, and then you’re done forever. Learning how to ride a bike is a classic diploma problem.

But most problems aren’t like that. They’re more like toothbrushing problems: you have to work at them forever until you die. You can’t, as far as I know, just brush your teeth really really well and then let ‘em ride forever.

—Adam Mastroianni

Three concepts I bring up often:

• TV-buying problem: A product category where all options look the same, none of the features make sense, and all of the specs are misleading. You pretty much need an expert to pick for you. Televisions, smartphones and health insurance are such products.
• Ryanair check in experience: A process that involves repeatedly refusing to buy things, give up personal data, or sign up for marketing spam.
• The ‘Ist’ and the ‘Soll’: How things should be on paper, and how they are in reality. It’s the difference between having rights, and being able to effectively enforce them.

Everyone is tired. Everyone secretly wants someone else to ring the bell. Host the cheap thing. Name the time and end. Say, “door is soft; leave when you must.” Put crisps in a bowl. Friendship is logistics performed tenderly.

—The Shadowed Archive

If you are an adult, and you have a problem with an organisation, your first steps should be:

1. Read the messages you have received from that organisation
2. Read the contract you have signed with that organisation
3. Contact the organisation’s customer service
4. Search the internet for existing answers
5. Ask the community

People often go straight for step 5, and I find that disrespectful of other people’s time.

When I’m working on an essay, I spend far more time reading than writing. I’ll reread some parts 50 or 100 times, replaying the thoughts in them and asking myself, like someone sanding a piece of wood, does anything catch? Does anything feel wrong? And the easier the essay is to read, the easier it is to notice if something catches.

—Paul Graham, Good Writing

“Sanding” is a great metaphor for the work I do. The same content, revised again and again over many years. This morning, I am revising my health insurance guide once again. I am applying new insights from dozens of reddit threads and hundreds of reader questions. I have found a more straightforward way to explain things, small details I had not mentioned yet.

A few of the things I enjoyed reading recently:

• Everything from Prickly Oxheart, but particularly Who are you without the next thing to do?, Do nothing and What if this is it?
• The whispering earring. A prescient cautionary tale.
• Speak White by Michèle Lalonde recently resurfaced in conversation
• When we get Komooted. When a community that you have built sells out to venture capital.
• Everything from Experimental History. It’s hard to pick a favourite after reading a dozen posts back to back.
• The symbol of earthly good, and the immediate object of toil.

I have finally started implemented visual regression testing on All About Berlin. It takes screenshots of elements, and compares them to old ones. If anything changed by even one pixel, I get an error. This helps me catch bugs and unexpected visual changes.

Since I already use Pytest and Playwright, I chose to use this library.

It’s time to bite the bullet and clear some technical debt. All About Berlin has unit tests, but they’re run manually, and some of them are a pain to update. As the website’s tools grow in complexity, manual testing is quickly becoming unsustainable. A change in the health insurance calculator logic might break the tax calculator, and I won’t notice until someone complains.

This cowboy coder has yee’d his last haw, and started rewriting his tests to be easier to understand and easier to update. The goal is to iterate towards a fully automated CI/CD pipeline. Pretty fancy for a blog!

“There’s lots of ways to be, as a person. And some people express their deep appreciation in different ways. But one of the ways that I believe people express their appreciation to the rest of humanity is to make something wonderful and put it out there.

And you never meet the people. You never shake their hands. You never hear their story or tell yours. But somehow, in the act of making something with a great deal of care and love, something’s transmitted there. And it’s a way of expressing to the rest of our species our deep appreciation. So we need to be true to who we are and remember what’s really important to us.”

—Steve Jobs, 2007