In 2016 I spent a summer on the Open Event project for FOSSASIA, through Google Summer of Code. I built a drag-drop session scheduler on Interact.js, wired up Stripe Connect so that event organizers could take payments under their own accounts, added PayPal NVP alongside it and put a revisioning layer on top of SQLAlchemy (with UI cues borrowed from Wordpress). Along the way I wrote about a dozen blog posts walking through how each piece worked. I thought I was publishing tutorials. A year later, I'm pretty sure I wasn't.
What I was doing was keeping lab notes. The reader of "Generating xCal calendar in python" was never some future person who also needed to generate xCal. It was me, 6 months later, trying to recover what I had worked out. The tutorial framing was a useful fiction. It forced me to explain things well enough that the explanation would still make sense outside my own head, and the person who needed that most turned out to be me.
Writing while you're still confused keeps the landmarks you used to find your way. The detour you took, the thing the docs don't say, the small mismatch b/w what a library claims to return and what it hands you at runtime. All of that goes the moment you stop being confused. If I had written the Stripe Connect post 3 months after I understood it, it would have been shorter, cleaner and of no use to anyone else trying to work it out.
Re-reading them now, the integration posts aged the best. Stripe Connect, PayPal NVP, the SQLAlchemy revisioning glue. Payment flows & audit trails are problems that keep coming back in the same shape even when the APIs change. The framework posts aged the worst, because Interact.js and the Flask idioms of 2016 do not stay still. And the GSoC diary entries (the "here is what I plan to work on this week" ones) were the least useful to anyone, myself included. Commentary on work-in-progress is rarely as interesting as the work.
The post that surprised me most was the one on adding revisioning to SQLAlchemy models. I wrote it breezily, as a recipe. The problem underneath it is one I have kept running into in every production system I have touched since. How do you give users a sane audit trail without making every bit of application code carry the weight ? The library I reached for (SQLAlchemy-Continuum) may not age well. The shape of the problem will. If I were writing that post today I would spend less time on the pip install and more on why the naive instinct (an updated_at column on every table, done) misses the point.
There's also a difference between writing publicly and writing privately that I didn't appreciate at the time. A private note lets you get away with "got it, moving on". A public one doesn't, because some imagined reader might quote it back at you. I had a scratchpad file going in parallel to the blog. It never caught the mistakes the blog did, because nobody was ever going to read it.
So, write things down while you're still working them out. The post-hoc version is always tidier and always less useful than the version where you were still confused, and the confused version is the one future-you needs. The paragraph that feels embarrassing to publish (the one where you admit you didn't know what the error message meant for 2 hours) is usually the paragraph that ages best.
I have retired those old posts. They did the job they were written for, which was cementing what I learnt that summer, and they don't belong alongside what I write now. This entry is where they used to live.