Articles

Notes, tests, and arguments.

A tutorial should do more than run, and an explanation should do more than agree with the first page of search results. These are my arguments about developer content, documentation, and the AI systems I build around them.

What Nobody Tells You About Error Handling in Production AI Agents
Hard-won lessons from running AI agents in production: the error patterns that actually break systems, and the patterns that fix them.
8 min read
Context Engineering as Heap Management: Accuracy Risks in KV Cache Eviction
A research-led comparison of KV-cache eviction strategies, including their accuracy risks and implementation trade-offs.
11 min read
Vector Search in the Browser: PGlite vs. SQLite-vec
A comparison of PGlite and SQLite-vec for browser-based vector search, including indexing, memory, and deployment trade-offs.
6 min read
Claude Code vs. Gemini CLI for Repository Refactoring
A workflow comparison of Claude Code and Gemini CLI for repository refactoring, verification, and human review.
3 min read
Quantifying the Engineering Velocity Impact of Technical Documentation
I analyze the structural correlation between documentation quality and engineering throughput, using DORA metrics and Accelerate research to quantify the ROI of technical writing.
10 min read
How Stripe's Technical Blog Became a Competitive Moat
I think Stripe’s technical blog compounds into a moat because it teaches, documents, and shapes developer trust long before a sales conversation starts.
11 min read
Why Devtools Startups Lose Deals Over Bad Docs
DevTools startups lose deals long before sales hears the objection. I explain how weak docs break evaluation, trials, and rollout confidence.
10 min read
From Engineer to Technical Writer: What I Kept and What I Left Behind
I explain which engineering habits still make me better at technical writing, which ones I had to drop, and how the day-to-day work changed.
9 min read
The Case for Shorter Technical Documentation
I think technical docs are often too long for the wrong reasons. Here’s why shorter docs usually work better, and where longer docs still earn their keep.
9 min read
Writing Release Notes That Developers Trust
Write release notes that let developers assess upgrade risk, understand product impact, and migrate without surprises.
12 min read
How to Write a Technical Tutorial That Actually Teaches
Write a technical tutorial that takes one reader from a clear starting point to a tested, useful result.
6 min read
Developer Onboarding Docs Should End in a Merged Change
Build developer onboarding docs around one supported setup path and a safe first merged change, with proof and recovery at each fragile step.
11 min read
Technical Writing for AI Products: The New Rules
AI product docs now need prompts, schemas, evals, and version boundaries. I explain the rules I would use to judge a technical writer for an AI company.
12 min read
How to Write a Changelog That Developers Actually Read
Write a changelog that helps developers assess an upgrade, find breaking changes, and understand what each release means for their code.
11 min read
Hybrid Search: Combining Bm25 and Vector Search for Better Retrieval
Hybrid search combines BM25 sparse retrieval with dense vector search. Here's how reciprocal rank fusion works, what it costs, and when the combination actually beats either method alone.
10 min read
Semantic Caching: The RAG Optimization Nobody Talks About
Semantic caching returns cached LLM responses for semantically similar queries, cutting API costs by 40-70% on the right workloads. Here's how the mechanism works and where it fails.
10 min read
Structured Outputs with LLMs: JSON Mode, Function Calling, and When to Use Each
JSON mode, function calling, and structured outputs solve different problems. Here's when each one actually makes sense and what they cost you.
12 min read
How Anthropic's Contextual Retrieval Changes RAG Architecture
The mechanism changes what gets indexed before the RAG pipeline runs a query.
11 min read
Reranking in RAG: Why Your Top-K Results Are Probably Wrong
Vector databases return results based on semantic similarity. I explain why that is rarely enough for production RAG and how a cross-encoder reranker fixes the problem.
11 min read
Vector Embeddings: a Guide to the Geometry of Meaning in Ai
Everything in AI starts with a vector. Here is how embedding models turn human language into high-dimensional geometry, why dimensionality reduction matters, and how to choose between OpenAI, Cohere, and self-hosted models.
14 min read