Write it down

I spent a few years writing down everything I learned about ClickHouse internals. Most of it I can’t read anymore. It lived in the internal tools of a company I no longer work for, and the day I left, it stayed there.

The habit came from Tinybird. For the ones who didn’t read my farewell post, writing things down was a big chunk of the company culture for the first years. We used Basecamp for it. We can argue whether it was the best tool, but it did the job.

Some of what I wrote in those years:

• A guide to designing a good sorting key. Gone, though I later automated the idea.
• Insights about uniq and its different flavors. Gone.
• A detailed explanation of how zero-copy works and the plan to migrate clients. Gone.
• The debugging process of a bug we were not able to find, which turned out to be a big old ClickHouse contention issue. This one survived, because I also wrote it here.
• A step-by-step walkthrough of how to analyze a query using system.processors_profile_log, with all the findings and the measures we applied. Gone.

The pattern is not subtle. The only pieces that outlived the job are the ones I bothered to publish in public. The rest exist as a vague memory of having understood something once.

For good or bad, I’m still working closely with ClickHouse and the habit came with me. The feeling of writing things nobody reads is still there, but I convince (or lie to) myself with the promise that this is a long-term investment. Eventually somebody will read one of them and learn something. Or an internal LLM will parse them and give better answers. Or I will sit down to write my 360 self-review and discover I have receipts.

So try to write the public version too. It costs an afternoon, and most of it is a customer name and a table schema away from publishable anyway. Nobody will read those either, but at least I’ll still have access next time I leave.

Inspired by Sean Goedecke on blogging about things you don’t understand yet, and this thread from Javi.