tech-notes

Personal tech notes. Raw markdown lives in notes/; images in images/.

On push to main, a GitHub Action transforms each note with publish: true into a Jekyll post and pushes it to herohua/herohua.github.io, which renders at https://herohua.github.io.

Tone & style

These notes share a recognizable voice. New notes should aim to match it.

• One load-bearing idea per note. Each post argues a single thesis and returns to it — "determinism isn't a high probability, it's a different kind of thing"; "taste is one judgment at every altitude"; "caching is end-to-end, not a flag." The title usually states it.
• Open with an italic epigraph. A one- or two-sentence blockquote in italics that compresses the whole argument, often with the punchline bolded. It's the note's thesis before the reader commits.
• Then a ## TL;DR bullet list. Three-to-five bullets that let a skimmer leave with the point. Key terms bolded.
• Lead with the counterintuitive, not the setup. The interesting claim comes first; the "here's the background" comes after. "The fixes that produced the headline numbers weren't exotic."
• Concrete over abstract. Real numbers (~12h → ~3h, 93% of prompts approved), real code (annotated before/after C# / Python), real systems (Redis, sitemaps, GitHub GraphQL). Claims are grounded in a worked case study, not asserted.
• Name the tasteless/naive version, then the better one. Most notes contrast "what a reasonable person would do" against "what's actually right, and why" — the why being the non-obvious part.
• Honest about limits. A recurring ## Honest limits / ## When this doesn't apply section names where the approach is worse, the tradeoff axis, the deliberate simplification versus state-of-the-art. Credibility over salesmanship.
• Structure for scanning. Tables for comparisons, Mermaid diagrams for architecture/flow, a closing "if you take only three things" recap. Section headers are declarative sentences, not labels ("Single-signal alerts page on weather").
• Voice. First-person plural for case studies ("we tried", "we built"), direct second-person for advice ("read your wrappers in execution order"). Confident but not breathless; precise; occasional dry wit. No filler, no hedging-for-its-own-sake, no emoji.
• Front matter is required. Every note starts with the YAML block below.

Writing a note

Create notes/<slug>.md (slug can be anything, e.g. kafka-rebalancing.md) with this front matter:

---
title: "Kafka rebalancing in depth"
date: 2026-05-19
tags: [kafka, distributed-systems]
publish: true
---

Your markdown here.

![diagram](../images/kafka-rebalance.png)

• title — required. Used as the post title.
• date — required. YYYY-MM-DD. Becomes the post date and the filename prefix.
• tags — optional.
• publish — set to true to publish. Anything else (or missing) stays as draft.

Image links should be relative (../images/foo.png) so they render correctly when previewed locally on GitHub. The publish script rewrites them to /assets/notes/foo.png for the live site.

Publishing

Just commit and push to main. The Action handles the rest. See .github/workflows/publish.yml.