Joan’s field notes for builders
Useful systems,
explained.
Hands-on technical writing with working code, honest tradeoffs, and a clear point of view.
56 deep dives in the notebook so far. Each one is built to help you understand the system—not just copy the setup.
From the notebook
Latest writing
Practical guides, careful comparisons, and lessons from tools used in the real world.
Giving an AI Agent a Memory: Patterns, Storage, and What to Forget
Build a practical memory layer for an AI agent, choose where each kind of memory lives, and design retrieval and forgetting that you can trust.
From API Keys to Scoped Tokens: Upgrading a Public API's Auth Without Breaking Clients
Migrate a public API from all-powerful API keys to scoped, expiring tokens: design the scopes, run both systems in parallel, and deprecate keys without breaking clients.
Designing Rate Limits Developers Won't Hate: Quotas, Headers, and Graceful 429s
Design rate limits that protect your API without punishing good clients: fair quotas, honest headers, and 429 responses developers can act on.
Designing an API Reference Developers Actually Read: Examples, Errors, and Auth Up Front
An API reference is read under pressure, mid-debug. Design it that way: auth before endpoints, a worked example per operation, and errors documented like features.
API Versioning Without Regret: URLs, Headers, and Sunset Policies Compared
Compare URL, header, and media-type versioning on real tradeoffs, and design a sunset policy that retires old versions without breaking clients.
BigQuery Partitioning and Clustering: The Cost Decisions You Make at Table-Creation Time
Partition and cluster BigQuery tables with intent: how pruning actually works, where each feature stops helping, and the decisions that are painful to reverse later.
Changelogs Are Product Writing: Entries Users Read and Releases That Earn Trust
Why the changelog is product writing, not a commit digest, and how to write entries that users actually read and act on.
Chunking Strategies for Embeddings: What Actually Changes Retrieval Quality
Compare fixed-size, recursive, semantic, and structure-aware chunking so you can choose a strategy that improves retrieval instead of quietly breaking it.
CI That Stops Rebuilding the World: Caching, Matrix Builds, and Flaky-Test Quarantine
Cut CI time with dependency and build caching that actually invalidates correctly, matrix builds that parallelise honestly, and a quarantine lane for flaky tests.
Cursor Pagination for Real APIs: Ordering Guarantees, Opaque Tokens, and Edge Cases
Implement cursor pagination that stays correct under inserts and deletes, with stable ordering, opaque tokens, and honest handling of filters.
No matches in this set.
Clear a filter or try another combination.
Published elsewhere