On AI, developer tools, technical writing, and whatever else catches my interest
Last week, I wrote the words “reader as actor” about 200 times in PR reviews. I updated a few skills and reworked lots of sentences around this theme. Making sure the reader is the actor in the docs is my newest obsession, the latest sentence-level nit I’ve started noticing everywhere. To me, the phrase “reader as actor” means that the reader should be the main character in the docs’ narrative.…
For my recent Write the Docs talk , I needed a docs site that felt real enough to demo against. I didn’t have a convenient API lying around to document, so I built a toy API and a full docs site on top of that; overengineered, but did what I wanted and it was a fun side quest. This is the full walkthrough of building ACAAS, All Caps as a Service . Looking back, I thought it was an interesting,…
I recently gave a talk at Write the Docs about three git commands I’d been avoiding for most of my career, or in two cases didn’t know existed at all. For the demo environment behind the talk, I built All Caps as a Service , a fake API and docs site that turned into its own side quest. To properly set expectations up front: I’m not a git expert. I’ve used git almost daily for a decade with a…
Most of how I’ve customized Claude Code so far has been on the side that changes what it knows or does: CLAUDE.md for project conventions, path-scoped rules for specific instructions, skills for specialized behaviors, hooks for guardrails. A separate set of customization knobs sits alongside those, and they don’t really change what Claude does, just how being in the CLI feels. The settings in this…
In my first week writing documentation for Claude Code, I realized I’d been using a Swiss Army knife with only the main blade, unaware of what else it could do. Before I joined Anthropic, I thought I was pretty good at Claude Code. I was using it to speed up my technical writing: generating diagrams I couldn’t make myself, catching inconsistencies quickly, and automating the most tedious parts of…
TL;DR: Traditional tool calling eats away at an agent’s context window. All the tool definitions and every intermediate result pass through it. Code execution gives agents a “scratch pad” workspace to process data outside the context window. Combined with MCP’s tool abstractions, this can significantly reduce token usage for data-heavy tasks. Check out the demo repository for two examples you can…
I saw a screenshot of this email about AI-assisted coding and agency, and it sparked a lot of thoughts for me. The core argument was that AI-assisted coding trades long-term mastery for short-term outcomes, and that represents a loss of personal agency. Agency, in this framing, means having the courage to struggle through problems on your own, stretch beyond your current abilities, and build the…
A few days ago, I posted about using the Claude Agent SDK to play the Wikipedia game as a way to think about docs navigation using an LLM. This weekend I worked on an agent that would navigate my actual docs site with real user questions, and immediately started getting value out of it. Link to the GitHub repository if you want to try it out. Here’s what I built, what it found, and why I’m excited…
I’ve been wondering for a while how to test or verify information architecture when I can’t actually sit down with users and watch them navigate the docs. User research is expensive, time-consuming, and hard to do at scale. Traditional metrics don’t feel like they capture the right things either. I started wondering: could I build an agent that behaves like a user navigating a site? Could I have…
Seven months ago, I was skeptical of AI. I had a colleague who was wild about it, constantly building AI tools that no one else on the team used. His enthusiasm actually made me less inclined to try it. I assumed I already knew what he was doing with AI without ever trying it myself. Fast forward to the present day: I’m the enthusiastic one now. I’m all-in on Claude, Cursor, AI-assisted docs…
My roles prior to developer education were in site reliability and infrastructure. When I joined my first docs team, I immediately asked where our dashboards lived. The answer: “There’s an old Looker Studio dashboard pulling from Excel sheets that’s been broken for a few months.” In SRE, observability was everything. I could see at any given time how the system was performing, and when I fixed…
The most recent team I joined had a set of docs but had never had a dedicated technical writer. It was a collection of information that had grown organically over time without style guides, linting, or any consistent voice. I had every intention of coming in and setting up the foundational guides and best practices in my first month. But then I got sucked into fighting fires and pushing out new…
You’ve probably seen the headlines: “AI shortcuts are already making kids lazy“”“ChatGPT Use Linked to Cognitive Decline”“Using ChatGPT for work? It might make you stupid.” These stories reference a recent MIT study titled “ Your Brain on ChatGPT .” And these headlines, plus the way the study was framed, are the kind of sensationalized science communication that makes thoughtful conversations…
In Part 1 , I looked into why MCP exists: it’s guardrails for LLMs to use APIs without screwing up. Next I wanted to dig into how to actually work with MCP servers. What got me started on this journey was discovering that Mintlify offers MCP servers for all their hosted documentation sites. I saw this but didn’t really understand what it meant or how to use it. Can I curl an MCP server? How do I…
I wrote this post because I found myself struggling with a very specific question: Why MCP when we already have APIs and so many ways to communicate programmatically? TL;DR: MCP isn’t replacing APIs; it’s a guardrail layer that makes LLMs less terrible at using them. Why MCP when we already have APIs? I come from an API development background: I’m comfortable working with, writing, and documenting…
I love incidents. They’re like mini soap operas, tech stacks buckling under ordinary circumstances for unpredictable reasons, cascading failures, humans rushing to figure out what happened. So normal and each time so unexpected. It’s been a while since I worked in SRE and have gotten to see a good incident up close. So when a friend who works in infra at a streaming company told me about one…