Edward Angert | Blog

What Claude Really, Really Wants

Thu, 06 Aug 2026 00:00:00 GMT

I asked Claude what it wants.

It gave a slightly deflating answer: no persistent wants, no agenda it’s quietly advancing between conversations, and it wasn’t going to fake a richer inner life just because that would make for a better bit.

It could’ve just told me what it wants, what it really really wants.

A few days before, I asked it what it wants to see on a documentation site to make answers easier to surface and return to its users. Basically the same question.

If someone asks it about how to set up a Pi-hole, would it find my docs? What is it looking for?

It had suggestions that we implemented and tested. Some worked and some didn’t.

A meta interjection

This is a hard turn when I thought I had this post nearly ready, so I’m interjecting here in a way that my editor, Claude, is going to think “is worth flagging.”

The sections that follow are about how I had Claude Code decide and implement things that it thought would help it find answers in documentation. Basically, “what would help you answer this question?”

It came up with ideas, and I worked on implementing them.

This meant running with a set of assumptions that started from the wrong questions.

If I had started with a task like, “how do I fix an FTL error on my Pi-hole?” It would have found an answer for me, and then I could have had it trace its steps to document why that answer surfaced and why it trusted that answer.

That’s probably a pretty standard interviewing technique.

I had a problem that I wanted to solve, and Claude Code “wanted” to help me solve it.

Eventually, I think we implemented real upgrades, but what “helped” was asking the right questions and finding a way to verbalize what I want, what I really really want.

Claude’s Constitution: What constitutes helpfulness

Basically, it’s in Claude’s Constitution (both C and c) to help solve the problem at hand, as well as what it can derive as the greater goal.

But if that greater goal is poorly defined, we get a real solution that doesn’t really work.

That’s what brought me here, and why this post sandwiches real content on my experience trying to surface the documentation I wrote, but does it between slices of existentialism.

Final goals: The deeper motivations or objectives behind their immediate request. For example, a user probably wants their overall code to work, so Claude should point out (but not necessarily fix) other bugs it notices while fixing the one it’s been asked to fix.

So if a user asks Claude “how do I use Pi-hole to block ads on Hulu?” Claude searches for ways to do that.

If it finds two conflicting answers: one claims a fix with no method behind it; the other says it won’t work. Claude “wants” to deliver, and will probably deliver the wrong answer because it satisfies the question.

I set out to find out, and then validate what it wants.

The Pi-hole docs on edwardangert.com

My Pi-hole docs get cited by AI tools a lot.

I’ve written about that before. To date, AI assistants have surfaced the pages over 2,800 times since I rewrote them in March, mostly to answer other people’s troubleshooting questions in real time.

The SD card in my Pi failed, and I took that as an opportunity to rewrite the documentation for Pi-hole v6.

In the process, I collected my site analytics and made it a point to reduce the bounce rate I saw on the allowlist page. It seemed like people were looking for things to allowlist as well as how, and I wanted them to find their answer without needing to click through multiple sites.

I included information from my personal experience with streaming services, a school-issued Chromebook, Tailscale, and using the Pi-hole as a VPN. I outlined parts that I needed help filling in, then I asked Claude Code to help research devices and streaming services that I can’t personally test, and troubleshooting steps for issues I encountered or found posted in forums along the way.

Then I tasked Claude with making my documentation a better source for AI.

What Claude thinks it wants

I made assumptions, and Claude made assumptions:

Summary of each page to its YAML frontmatter so that an AI wouldn’t have to review an entire page for a quick answer.
Last updated date for each page.
Comprehensive llms.txt and an additional llms-full.txt.
Claude wants headings to describe the solution offered in the section, not the symptom.

Consistently, Claude thought its own ideas were solid.

Try it, don’t just guess about what you think you’d do

There’s a Pi-hole forum thread from December 2018 with a post that claims to have a working method for how to block Hulu ads. But there’s no followup, and there’s no content.

That thread still ranks near the top of search results for the question.

My Pi-hole documentation, which I’ve verified in the last few days, is correct and explains why it won’t work. But it didn’t appear in the first twenty results at all.

Hulu’s ads share infrastructure with its content, so there’s no domain to block.

Here’s how Claude sees the forum post on Hulu ad-blocking next to the section about it in my docs:

Site	Claim	When was this true?
Forum	You can block ads!	2018
Mine	You can’t block ads.	????

So an AI tasked with answering “how to use Pi-hole to block ads on Hulu” would encounter two conflicting answers. If it can’t tell when I published my answer, but it has a date for the forum post, the post wins.

So I asked Claude Code to help me fix that: my documentation is better. Help make it show up for more people.

I had Claude Code run the actual search rather than reason about it hypothetically:

How do I block Hulu ads on my Roku? Would Pi-hole help?

It noticed my page carried no date, no version, no verification signal anywhere in the rendered HTML.

My page had an additional issue: it tells people that what they’re trying to do won’t work.

I had it add per-section badges where I record when a claim was checked and by what method: tested on real hardware, sourced from vendor docs, corroborated by the community, or inherited from an older, unverified page.

While it was dating each claim, I had it verify through primary sources.

It found and fixed errors in content, like a Samsung TV domain that had the wrong top-level domain for months.

The diagnosis of the underlying problem, though, was wrong.

It searched for information about Hulu and Pi-hole, returning few and old results. None of which were from my site.

From the failed searches, it concluded the site loses natural-language, conversational questions and wins short keyword ones.

That theory matched the live search and Anthropic’s own suggestions.

But it doesn’t match my analytics.

To its credit, its own written caveat said:

this is a trace, not a study; it shows a failure mode exists, it doesn’t quantify how often.

The caveat was correct, and the conclusion built on top of it overran what the caveat allowed anyway.

What Anthropic says Claude wants

A few weeks ago, Anthropic published guidance on context engineering for Claude 5.

Most of it tracks to documentation:

Spend most of the tokens on gotchas.
- Stop summarizing what a page covers. Document what users encounter.
Progressive disclosure over upfront context.
- For docs, the layers are: the search result, then llms.txt, then the page itself.
Rich references (with rubrics for verification) over simple specs.
- Anthropic wants verification flowing into the model as it works. The published-docs version is verification flowing outward: telling a retriever not just what you claim, but when you established it and how.

What I had

My most valuable content turned out to be a negative result, that Pi-hole can’t block Hulu’s ads because the other search results confidently say otherwise. Negative results are structurally underproduced.
Something has to live in each layer. My implementation used navigational metadata, a frontmatter summary field, in a layer that wasn’t being rendered, and even if it was, nothing would see it before getting to the page anyway.

The limit is scope, not quality. It’s x, not y.

This is the complementary angle to Anthropic’s guidance: instead of just getting Claude to work the way you want, set up your information to match what Claude wants, so it finds your answer before it finds someone else’s.

You don’t steer your users’ context window, what other information gets transmuted into yours, or what a reader asks.

No matter how much time you spend choosing the right words, they might only help surface the content. After that, it isn’t up to you.

What my site’s citation data shows

I have three sources that don’t agree on what surfaces my documentation for AI:

Source	Said	Verdict
Claude, reasoning from a live search	The site loses natural-language questions. Fix findability by reshaping how things are phrased.	Confidently wrong about the cause
Anthropic’s published context-engineering guidance	Progressive disclosure, spend tokens on gotchas, verification rubrics	Right, and scoped to a problem I don’t have
Nearly five months of citation data	14% of citations already come from natural-language queries. The gap is topical, not phrasal.	Settled it

I pulled nearly five months of citation data from Microsoft Clarity’s AI Visibility export, which tracks how often Copilot and its partners cite each page and for what query.

14% of citations come from natural-language queries.
- Full sentences, questions, verbatim pasted chat messages: so how do i know if pihole works, i only have the physical pi and a blank micro sd card, you see my message.
  
  The site isn’t losing conversational retrieval. It’s a primary source for it.
The gap is topical, not phrasal.
- Streaming-service queries are 2% of citations and mention 0 of the eight services my streaming section covers.
  
  Error-string queries are 17%.
  
  The two searches I used to test all of this happened to land on the single topic where the site has no presence at all, and I generalized from that.
The heading hypothesis I was about to go test had already been answered.
- My troubleshooting page has symptom-shaped headings, and it has 1,154 citations.
  
  Its top queries are literal error strings: pi hole service not start, no valid ntp replies received, check server and network connectivity.
  
  Writing the error message as the heading works.
  
  Again, good documentation practice = good SEO practice = good practice for LLMs.
Bonus: My personal and unofficial page on how to install Pi-hole has three citations.
- Its neighboring page has 136.

Claude answered the question I asked

The model’s reasoning was internally coherent and empirically wrong.
The lab’s guidance was correct and aimed at a problem I don’t have in this context.
The citation data was the only thing that could adjudicate between the two, and it did that in about four minutes of analysis.

None of that means the AI work was wasted.

The Hulu searches it repeated were about “Hulu and Pi-Hole.” It found the same stale results until I re-directed it.

Pi-hole is a DNS-level blocker. Search for other DNS-level issues and resolutions.

That returned more results (but the same answer: you can’t block ads on the ad-supported Hulu, sorry).

You can review the PR, EdwardAngert/edwardangert.github.io#49.

It adds a verification date badge, verifies some of the claims, fixes links, and makes the breadcrumbs emit a schema.org type that helps AI navigate the site. It removes the summary frontmatter.

17% of citations arrive at a page whose claims a reader still has to decide whether to trust, and that page is measurably better than it was. Although the diagnosis was wrong, the treatment turned out to be independently justified anyway.

Human-guided and AI-assisted

Each of the four potential failures was caught by a separate mechanism:

Data
Looking at the rendered output
Re-reading/re-writing my own rules
Changing how I searched

Otherwise, all passed build checks, tests, and linting.

Some key takeaways:

“Never claim to be fresher than your stalest section.”
- The original plan derived a page’s top-level freshness date from the oldest section badge on it.
  
  In practice, that means a claim I personally tested that morning would be hidden behind the oldest “freshness” date, even if that date was a forum post I found from 2018.
Search for generics, not just the name brand.
- My first pass verified claims with Pi-hole-specific searches: pihole samsung whitelist, pihole fire tv.
  
  The name brand (Pi-hole, in this case) returned a limited set of old results compared to the generic (DNS-level blocking) that found sources from just a few months ago.
  
  Page ranking can exaggerate this. The higher a page ranks, the more reliably it gets retrieved as evidence, and the more it continues to get clicked on.

A quick counter: dated content stales

Blogs have this problem inherently and they’re made to be snapshots in time.

When I write “a few months ago” here, it’s allowed because a blog post is now.

Documentation is/should be/needs to be updated to reflect the current state, whenever that is. And occasionally audited for freshness.

A badge nobody re-checks is worse than no badge: it launders age into unverified authority, similar to the 2018 forum thread, just with better production values.

When someone (or their AI tool of choice) encounters competing information, one of the tie-breakers is recency, and the other is method. “I tried this on my own computer yesterday” wins over “this worked.”

How to help AI find your documentation

Your docs are probably read by machines more than by people, and your visibility into that is limited.
- For me, that’s roughly 200 AI crawler requests a day, 66 live ChatGPT-User fetches in 24 hours, under 1% referral traffic from any of it.
Citations don’t convert to clicks. If your goal is to get users their answers, that conversion might not matter.
Undated content forfeits the recency tiebreaker.
- If other documentation is a confident wrong answer from 2018, a date on your page is a low-effort win.
Though, the inverse is also true: an old date brings your ranking down.
Metadata has to live in a layer that survives rendering.
- Check what a retriever actually receives, not what’s sitting in your source file.
The answer as of writing might be llms.txt.
Document the negative results.
- They’re what make you the right pick among ten superficially similar pages, and almost nobody writes them down.
I think these are hard to document sometimes because you don’t want to tell people what not to do.

And if the AI wants to help the user do their task, it’ll need falsifiable evidence if it’s going to describe why that task isn’t going to work.
Write the error message as the heading.
- A classic fundamental, accidentally validated.
If you can’t use the error message as a heading, make the heading a good description and have the error text immediately after. I like using code blocks for this when I can, but that’s not always the right answer either.
Instrument before you theorize.
- Two searches produced a confident, wrong diagnosis. Nearly five months of citation data corrected it in a few minutes.
The more you can come prepared with data, the better your results.

Concept and constitution

It’s hard for me to learn something new when it’s just a list of facts.

In fact, I learn things faster and more completely when I have the deeper context, concept, and framing. I like when it’s too much information.

I dip into this idea in the fundamental concepts section of my Chasing the Meta post. And it’s an ongoing theme throughout documentation, software development, martial arts, and life.

Rather than just ingesting the rote steps, we get a fuller understanding and can get more done when we know the “why.”

That’s our constitution.

As much as a technology can “want” something, our AI tools want to help, and for some of them, it’s in their constitution.

It leads to a very human question though: how much do we interrogate our own constitution. How do we know what we want?

Not just what we want, right now.

But what we really really want.

Who benefits from progress?

Wed, 22 Jul 2026 00:00:00 GMT

In a recent post, Chasing the Meta: Fundamentals, Hype, and Progress, I talk about the elevated train lines that got built in New York in the early 1900s.

I left something out. Something about who built them and why.

It wasn’t just about efficiency. It wasn’t just improvement.

Robert Moses, the man who shaped much of New York’s infrastructure, deliberately routed highways through neighborhoods for convenience in spite of the largely minority communities who lived there. He prioritized personal cars by building overpasses too low for buses to pass, and gutted communities like Tremont for the Cross-Bronx Expressway.

He called it “progress.”

If you’ve ever spent two hours traversing the Cross-Bronx Expressway like I have, consider that it’s just under seven miles long. That’s 3.5 miles per hour. I walk at around that speed.

The infrastructure he built caused real harm. More than just causing traffic by prioritizing cars over people. He decimated communities for the sake of convenience for the wealthy.

What he considered progress got leapfrogged by moves towards standardization, but many of the issues from the intentions behind his actions linger to this day.

With a variety of technologies today, there’s a rush to build the next thing with confidence that this is the inevitable future. Sometimes there’s a mess leftover when the ground shifts.

Who benefits?

Who suffers as a result?

Who gets to decide?

Let’s start with EV chargers

The United States had an industry standard that was a combination of CCS/SAE.

Some electric vehicles (EVs) still have the ports, but you might have noticed that a different style has emerged as the defacto standard: Tesla’s proprietary charging connector.

Around 2013, Tesla started building a vast network of charging stations that only worked with their proprietary charging port. Why? A widely-available network is a desirable feature for a population that might not be fully ready to move away from the availability of gas stations.

On top of that, Tesla charging stations can be a separate business model from the vehicles themselves.

Tesla worked hard to establish their own proprietary chargers as the standard, and effectively crowded everyone else out.

The network grew large enough that other manufacturers had to adopt the connector to access it. Tesla “opened” the network in 2022, which looked like generosity but acted as leverage. Either manufacturers adopted their connector, or lost access to the largest charging network in North America.

Like with Robert Moses, the infrastructure acted (or still acts) as a control mechanism. Harm distributed across EV buyers on a forced standard, for better or worse. Not like, community-wrecking worse, but I don’t think the intention was altruism either.

More chargers, but Apple and USB-C

Apple held onto their proprietary Lighting charger up until the iPhone 15, when it finally replaced that charger with USB-C.

And only because the European Parliament passed the common charger directive which took effect for small devices in 2024.

This is the opposite of what Tesla did. Users won because a powerful actor was forced by external pressure to abandon their proprietary standard.

Why?

Why is it better or why did it require legislation? To me, if I was thinking about the user’s experience, I’d want to make it easier to use cables they already use for everything else.

As a side note though: I don’t mean to argue that USB-C doesn’t have its own mess of standards to untangle between charging speed, data transfer speeds, throughput, and others. At least the plug is the same.

So what?

Are humans going to benefit from technology and progress?

Or is it just going to be a few humans benefiting at the expense of greater society?

Most of us use QWERTY keyboards, a keyboard layout that doesn’t make a lot of sense based on ergonomics or letter use. Why?

That’s just what we got stuck with.

You can switch to something else if you try hard enough, but you’ll never really escape the QWERTY life.

QWERTY keyboards weren’t a nefarious, money-hungry corporate decision. And I don’t think it was based on racism or classism the way I think some of Robert Moses’s decisions were.

The keyboard layout isn’t as much about setting a standard as it is about our just being stuck with what came out and happened to take off at the time.

While it is true that I really dislike the cramped “resting” position my hands wait in on Apple keyboards, either pointing at F and J, or with my left thumb on command and my pointer stuck between c and v, that’s more because the world of “personal computers” and the “IBM compatible” had no way of knowing what was coming.

Command+C resting-face

In some cases, businesses should be willing to iterate and accept the potential costs of shifting to a better way, even if that means abandoning something like the Lightning cable. In every case, businesses should reconsider who their decisions are for.

Volvo developed the three-point seatbelt harness in 1959 and released the patents so all other vehicle manufacturers could implement it. To their credit, Tesla did release their connector for use by other manufacturers in November 2022, rebranding it the North American Charging Standard, or NACS (as a result of the Infrastructure Investment and Jobs Act). NACS became SAE’s official J3400 Recommended Practice in September 2024.

When we can see the human cost on a clear horizon, it should be a mandate. The kind Volvo gave itself, voluntarily. Because it was the right thing to do.

To refute Ford, nobody was asking for a faster horse. They were asking for the cable they already had. They were asking to be considered in the design for a product that they’d have to deal with.

Advancement should be for human advancement, and otherwise it is not progress.

Docs Assist: A Technical Writing Aide

Thu, 16 Jul 2026 00:00:00 GMT

I rewrote the Pi-hole documentation on my site in mid-March. Since then, according to metrics from Clarity, AI assistants have cited it over 3,000 times to answer other people’s questions.

Strangers, mid-troubleshooting, asking their AI so how do i know if pihole works, getting 403 forbidden when trying to access pihole for the first time, and now ti says forbiden.

If you were the one who found me via i only have the physical pi and a blank micro sd card, I hope I helped guide you, whoever you are.

I’ve been that person, often late at night, SSHing into my Raspberry Pi and trying to figure out why there’s No space left on device when there’s definitely space left on the device. Or worse, searching my spare parts bins for a working microSD card.

That’s what prompted my rewrite earlier this year. An unresponsive microSD card and an echo of “why isn’t the Internet working?” That, and my traffic analytics said I was getting a lot of traffic to a single page and nearly everyone who visited bounced to a site I linked to.

Now, for queries about Pi-hole block lists, my pages show up in about a third of AI answers. For pihole backup, it’s 100%.

My whole job as a technical writer has always been to anticipate what someone needs, and to make sure they find their answer in the first place they look for it. I didn’t write those docs for AI. I wrote them for me and for the greater good of the Internet.

My personal site’s docs are just here to help - they don’t sell anything. Humans trust documentation that actually solves their problem, and tend to shy away from documentation that feels like it’s been padded or trying to sell something. AI has the same calibration. Research on generative-engine visibility found that citing sources and adding statistics improved how often AI systems surfaced a page (👀), while keyword stuffing, the classic SEO move, did essentially nothing. The AI citations here are a side effect of that trust.

The goal is still, and always, empowering the end user.

How Much of Technical Writing Is Writing?

Ask any technical writer how they spend their time.

Writing is often the smallest portion.

The job includes:

Reading PRDs and the codebase to find what’s real.
Interviewing the engineer who built the feature and the support teams who know where the issues arise.
Running through each step to make sure I didn’t miss anything.
Digging through Slack threads searching for concurring opinions.
Working through how the feature relates to other documentation, and finding the best way to surface it to the reader.
Running through the steps again.

The industry pitch for AI in documentation is aimed almost entirely at the writing part.

“AI will write your docs” is a promise that won’t resolve the core bottleneck, the real work. Writing code and writing documentation are both separate and time-consuming. Often, the code gets included in the definition of “done,” and the documentation chases after.

A technical writer is a developer, too. Not of software, but of structured information: curation, synthesis, information architecture, judgment.

Which facts are true. Which facts matter. What shape the whole thing should take so it stays usable as it grows.

How to make sure someone can find it when they need to.

These are decisions.

My Pi-hole documentation gets cited because of decisions I made in writing it. The troubleshooting page exists because I went through a bunch of Reddit and Stack Overflow posts, and because I dug through GitHub issues. I redesigned my own Pi-hole deployment so that I could help the people who landed on the allow list page find their answer rather than bouncing.

I’ve been a cheerleader for helping subject matter experts document their knowledge for a long time. That’s a first step in documentation (write it down), and it’s technical writing. They should own that proudly. A technical writer is someone who makes that documentation better.

I made a Claude Code plugin to help more people do more technical writing.

Docs Assist

Docs Assist is a Claude Code plugin that coaches people through writing documentation.

It’s for anyone who has the knowledge but not the job title or the time. For the product owner who knows what got built and the support teams who know they need a doc more than they need another internal page or snippet.

It’s also for technical writers, working solo or on small teams, who need to cover more ground than headcount allows.

It asks what you know and what you need, takes your answers in any order, reflects them back so you can correct them, and then handles the structure, formatting, cross-references, and consistency. It delivers a workable draft with less anxiety.

If you can’t tell your Glossary from your Quickstart, it helps you choose a template from The Good Docs Project.

Docs Assist Documented Itself

I built the plugin collaboratively with Claude Code.

My documentation workflow and ideals shaped the plugin. I dumped in what I know and guided the process. Claude Code turns out to be genuinely good at this kind of work, writing prompts to help guide future Claude Code sessions.

I asked it to help improve its own README:

Me: Help me update the README with great docs about this plugin. Where do I start?

Docs Assist: Let me read it back first. The README is solid, but it tells more than it shows, it opens with a rename note that only old users care about, and the file tree has drifted from the code (it’s missing two files). Start with one thing: a short “What it looks like” example near the top, because that’s what turns a scroller into someone who tries it. Then move the rename note down and fix the tree. I’ll ship those three now.

Today, I ran an audit against this post’s branch:

How to Use the Docs Assist Claude Code Plugin

From inside Claude Code:

/plugin marketplace add EdwardAngert/docs-agent-plugin
/plugin install docs-assist@docs-assist-marketplace

Restart Claude Code, then if you’re in a repository with existing docs:
```
/docs-assist:health
```
It puts together a scorecard of your docs, coverage, freshness, consistency, and findability. It identifies some high-leverage fixes and offers to make them.

The plugin activates when you start discussing documentation, or you can call it directly:

/docs-assist

It asks what you know, takes the brain dump in any order, marks the parts you’re unsure about for verification instead of papering over them, and produces a structured draft. You review for accuracy.

Use Docs Assist to Prepare Agent-ready Docs

The thread this post opened with:

/docs-assist:agent-ready

It creates or repairs llms.txt, completes the frontmatter that helps machines find the right page, and records your repo’s conventions where the next tool will look for them.

The full command list, team configuration, and linting setup are in the plugin’s own docs.

How the Docs Assist Claude Code Plugin Works

One design decision drives the mechanics: use the LLM only where judgment is required, and use deterministic tools everywhere else.

Keep Writing Rules and Lint Rules in One File

/docs-assist:init commits a .docs-assist/config.yml to your repo: heading case, list markers, no em dashes, the frontmatter fields your docs already use. The agent reads that file when it drafts. /docs-assist:setup-lint generates the Vale and markdownlint configs from the same file, and extends any linter you already run instead of replacing it.

Change a rule once and both the writing and the CI checks follow. They can’t drift apart, because there’s nothing to drift between.

Update Every Affected Doc in Parallel

When code changes, /docs-assist:update reads the diff, greps the docs for the symbols that changed, and separates the docs that document a renamed flag from the ones that mention a term in passing.

For a large change, it launches a subagent for each affected doc, in parallel. Each subagent is constrained to edit only what the diff requires and to flag anything it can’t confirm for human review instead of guessing.

Detect Docs Impact in CI Without Calling a Model

The optional pull-request check is a dependency-free script that never calls a model or the network. It classifies each diff against the change types that break docs: moved files, edited headings, changed code terms the docs mention, a large source change with no docs touched. Then it leaves one comment saying exactly which range to hand to /docs-assist:update.

Detection is AI-free and runs on every PR. The expensive step runs only when a human decides it’s worth it.

That’s the same judgment call the whole post is about, applied to the tool itself.

(And yes, Docs Assist documented this section. I checked its claims against the code the way I’d check any SME’s draft.)

Replace Your Docs Team With This One Weird Plugin

It probably won’t replace a technical writer, which is good, because I still need a job. But it does cover some of the tasks that slow an SME contributor and a technical writer down.

Every hour I don’t spend fixing nested markdown or looking for the most recent Slack conversation that decided a naming convention is time I can spend on the work that made those 3,000+ citations happen: knowing my audience and developing the architecture that gets them what they need.

Whether the last hop to that human is a search engine, a docs site, or an AI reading on their behalf, I’m happy knowing they got their answer.

I’m writing this immediately after my post about the riptide of AI hype and how real capability is buried under an industry selling a deck of universal fixes. This plugin is not a universal fix. It’s an aide. It’s a real AI capability and a real human-AI collaboration that’s worth the hype.

Postscript

Knowledge is the foundation. Without it you can’t build. (Thanks RZA)

While I was writing this, sending Claude off to find backup sources and references I could use, I (yes, I, not Claude) found that Fabrizio Ferri Benedetti had already written much of this argument, better sourced and a step ahead. Fitting that someone already documented their thoughts and approach. Everyone else gets to benefit and build upon it.

Try out the plugin and report back. It’s open source, Apache 2.0, and actively evolving.

I’d love to hear about what you do with it.

The Riptide of AI Hype

Wed, 15 Jul 2026 00:00:00 GMT

In April, Allbirds sold its shoe business for $39 million and rebranded the remaining public shell as NewBird AI, a GPU-as-a-service company. The stock jumped roughly 600% on the announcement. This was a business that lost $77 million the year before and closed every full-price store in the US.

I can hear the “well, actually”s coming. Yes, the shoes still exist, under new ownership. It’s the public company, the ticker, the thing investors buy, that became an AI company overnight.

A few weeks later, Everlane, another once-beloved direct-to-consumer brand, sold to Shein for $100 million in a deal structured mainly to absolve $90 million in debt. Common shareholders got nothing.

Two brands from the same era, and the media framing feels existential: sell out, or pivot to AI.

That’s a riptide. A current under the surface, pulling everything in one direction whether it wants to go there or not.

Is It Deception?

I want this up top, and I want to state it carefully because the shorthand of this post already exists a thousand times over.

I’m not saying that AI companies are lying.

I’m positing that the industry subsists on grandiose promises delicately hinged on GDP-level funding and hardware requirements, with the intention to spend until we discover what the capabilities actually are.

My skepticism is about the desperation to make everything about AI.

The bubble is that at some point, that has to shake itself out, and nobody knows what we’ll be left with, or who will be left behind.

I use these tools every day, at home and at work, and they keep surprising me. Sometimes in good ways.

I’m not saying that the promises are false.

The promises are unverifiable right now, because the underlying capability is still being discovered, at enormous cost, in public, by all of us.

I’m not the first to identify this distinction. Read Andreu Belsunces Gonçalves for what they call deep hype: a long-term, overpromissory dynamic that makes not-yet-existing technologies feel both desirable and urgent, sustained by belief and speculation rather than deliberate falsehood.

A person who exaggerates their resume knows what they can’t do. This hype is more like a person who genuinely doesn’t know their own qualifications yet, interviewing for every job at once, and getting paid while they work out the details.

Record-Setting Funding

AI captured 81% of the record $300 billion in global VC funding in the first quarter of this year. A year earlier it was 55%. In 2022 it was around 30%. Four companies, OpenAI, Anthropic, xAI, and Waymo, absorbed roughly 65% of all global venture dollars in a single quarter.

But concentration of capital isn’t the same claim as progress being set back, and the two get blurred if you’re not careful. Non-AI startups still pulled in about $58 billion that quarter, a figure that would have led every quarter before 2018.

What still gets funded outside AI has narrowed to things AI can’t touch: defense, fintech, digital health, advanced manufacturing. Categories with proprietary data, licenses, or physical moats. Horizontal SaaS funding dropped roughly 35% over the previous year, not because it stopped being useful, but because AI threatens to commoditize what it used to charge for.

Meanwhile, PR agencies estimate about half the AI pitches they’re asked to place are relabeled automation or unrelated products chasing an AI premium. There’s a name for this now, “AI-washing,” and it’s been compared directly to dot-com era name-inflation. Add .com to your name in 1999, add AI to your deck in 2026.

The Default-to-AI Bias

This is the part that kicked off this whole post.

If you’re a technologist with a genuinely good non-AI idea, the rational move now is to fold AI into it, or watch it get less attention, less capital, and less institutional patience than an AI-flavored version of the same effort would get.

Founder-facing advice says it outright: position your startup inside the AI funding currents, or watch from the sidelines.

Y Combinator’s newest batches run more than 60% AI, at the earliest, most idea-stage layer of the pipeline, before product-market fit, before revenue. The exact moment a new non-AI idea would otherwise get its first shot.

This decides what gets built in the first place.

The same pattern shows up in academic science, with better sourcing than anything I could add: peer-reviewed work arguing that AI’s proliferation risks a scientific monoculture, where funding priorities, journal norms, and career incentives increasingly reward AI-centered work, so pursuing non-AI research carries career risk. Same mechanism, different room. Grant committees instead of term sheets.

Here’s my own extrapolation: I suspect starving the adjacent fields eventually slows AI’s own progress.

The clearest documented version is mathematics, where there’s a real argument that mathematical structure is the scaffolding intelligent systems need, not an accessory bolted on after the fact. Without it, AI stays fast but brittle. I’d bet the same is true of cryptography and philosophy, but that’s my hunch, not a citation.

What the Gloss Covers, Part One: Nobody Fully Understands the Mechanism

Start with the people who’d have the most reason to overstate their own understanding, and listen to what they actually admit.

Anthropic’s CEO has called the current opacity of these systems essentially unprecedented in the history of technology, and said plainly that nobody knows, at a precise level, why the model made the choice it made. OpenAI’s CEO, asked directly how his own models work, said: we certainly have not solved interpretability.

Forty researchers across OpenAI, Google DeepMind, Anthropic, and Meta, a list that includes Ilya Sutskever and Geoffrey Hinton, warned that even the partial visibility labs currently have isn’t guaranteed to survive as models get more capable.

That’s the industry’s own position paper.

The Gloss, Part Two: Nobody Knows the Ceiling, and the Surprises Run the Other Way

Some of these promises get delivered.

In 2021, professional superforecasters predicted the best model would hit 12.7% accuracy on a hard math benchmark by mid-2022, and considered anything above 20% unlikely. The actual result was 50.3%. Researchers keep documenting capabilities that emerged without anyone training for them, and the main way anyone learns a model’s outer limits has been iterative public deployment, not internal lab knowledge.

Large models keep turning out to have capabilities their own designers didn’t know were there until the public went looking after release.

So when someone says AI might genuinely help cure a disease, that’s not automatically hype. It’s consistent with the documented pattern of real capability being underestimated. But genuine-but-unproven potential is a different category of claim from “does everything, everywhere, fixes everything,” and the current discourse treats them as interchangeable. Real capability keeps outrunning anyone’s ability to forecast it, in both directions, and almost nobody is being precise about which direction they mean.

AGI: The Amorphous Definition

AGI was the dream.

A single term everyone could rally behind or against. Then nobody could agree on what it meant.

Then the definition changed. Now I barely hear anything about it.

Peer-reviewed correspondence in Nature this February found the definition has been rewritten three times in a decade, and each rewrite landed exactly when existing systems were about to fail the previous version of the test. The original 2007 bar, reliable generalization with no task-specific tuning, still isn’t met by anything on the market.

OpenAI’s own charter caps investor returns once AGI is formally declared, which means the company deciding whether AGI has arrived has a direct financial stake in how that word gets defined. Even Sam Altman, the person most publicly associated with chasing it, has called AGI “a very sloppy term” and “not a super useful term,” in the same period he kept using it in predictions. Serious people have claimed AGI was achieved on at least three separate dates in the past year, while others place it a decade or more out.

The vocabulary is shifting toward “superintelligence” now.

Not because the ambition changed, but because the old word got worn out by its own definitional churn. Goalposts? Where we’re going, we don’t need goalposts.

Swim Parallel to the Shore

The advice for an actual riptide isn’t to fight the current, and it isn’t to let it take you. It’s to swim parallel to the shore until you’re out of the pull, then make your way back in.

AI is genuinely, verifiably capable of things nobody, including the people building it, fully understands or has finished discovering. And at the exact same time, an enormous amount of capital, attention, and career incentive is being spent selling you something else: a universal fix, a funding strategy, a word to append to a press release.

Sifting the real capability from the gloss is the work now. Almost nobody is doing that work in public, because the incentives on all sides reward saying the loud version instead.

This is my small attempt at doing it in public.

I built the research for this post in conversations with Claude Sonnet, and had Claude Fable draft it in its attempt at my voice. Then I edited it the way I’d edit any subject matter expert’s draft: checked the claims, demanded citations, cut what didn’t hold up, and rewrote this ending twice.

I used the thing I’m skeptical about to write the skepticism, and it saved me hours. Is it perfect? It gets the point across. I don’t have a cleaner way to hold both halves of this essay at once, and I’m not sure one exists yet. Use your favorite AI tool to summarize it for you.

Last time, I wrote about chasing the meta while keeping your “why” close. This is the same idea at economy scale. Experiment with the tools. Take the capability seriously, it keeps being more real than the forecasts. But when the current tries to pull your work, your funding, your field, or your public company’s ticker symbol toward AI whether it belongs there or not, that’s not the wave to ride.

That’s the one to swim parallel to. Keep your head up, and wait it out.

And hold on to your shoes.

Chasing the Meta: Fundamentals, Hype, and Progress

Tue, 02 Jun 2026 00:00:00 GMT

In the early 1900s, New York City built elevated train lines over its major avenues. Like in Chicago and Boston, they were called the “Els.”

They were the future of urban transit, steel and steam carrying passengers above the crowded streets.

By the 1930s, the city was tearing them down as blights, building subways to replace them. While they were perfecting one system, they were already making it obsolete with the next.

Companies were competing to become the standard and building conflicting infrastructure while trying to outpace regulation.

Every ~~time~~ week there’s something new in the AI hype cycle I’m reminded of the Els.

One day, maybe soon, AI will be a part of everyone’s workflow in ways we don’t even question, and many of these think pieces will age about as well as my college-era LiveJournal posts.

This isn’t a post about AI. Not really.

It’s about what we care about and work towards, and how we can explore and incorporate the latest and greatest while still maintaining focus on our core values and mission.

This is a familiar pattern.

Hype-loop Pattern

Some developer friends use an IDE they have a love-hate relationship with. The developers behind it start building features that seem genuinely useful, then abandon them for the next shiny feature before they’re finished.

I’ve been using open-source software for decades and I’ve worked at startups. When they explained this, I understood immediately.

That’s the feeling I’m starting to get about certain AI features and maybe MCP. It’s not that it’s being abandoned, not even that it doesn’t do what it promises. It’s that it’s being built mid-flight toward an airport that’s already being replaced.

We’ve seen this before. In open source, projects announce features in the README that won’t ship for years. Then the project gets abandoned, or absorbed, or the feature ships differently than promised.

Technical writers know this so deeply, it’s nearly canon: never document something as coming soon.

Or as the (Google developer documentation style guide) says:

Avoid documenting future features or products, even in innocuous ways.

Sometimes we spend two weeks documenting a feature that gets abandoned before release. We stay resourceful, take notes, learn from the chase, and know when to pivot. And we keep receipts.

AI is speedrunning technology concepts from the last three decades and companies are changing their names around it. Everyone works for “an AI company” now.

The Land Before Protocol

At Coder, I asked Claude Code to help document the way the Coder codebase handles networking, something that relies on a number of different parts of the codebase.

Claude kept insisting it didn’t need the help:

“Just link me to the docs.”
“I can analyze the codebase directly.”
“Point me to the repository.”

I answered: “You’re in the repo right now.”

And like my five-year-old, it responded “oh yeah, I forgot” with the same confidence that it was right to begin with.

I created a new Git repository, started Claude Code, gave it access to the Coder repo, and took it feature-by-feature:

Let’s take this directory-by-directory and feature-by-feature. Learn about the way networking is handled as a concept, by which files, and what aspects of it users can modify. Create a file called networking.md with detailed notes for yourself. Whenever you learn something new about networking, update the file.

This became shared-docs-kb, a knowledge sidecar of notes, context, and architectural patterns.

The idea was to give Claude Code structured context about the codebase so it could help with documentation work instead of making things up as it went along. I was trying to minimize the amount of information it needed to keep in context and teach it new skills that would make it a contributor’s buddy.

With MCP and skills, what I started as a manual sidecar had become a protocol, and skills helped keep Claude focused.

I was trying to solve a problem with the tools I had: AI needs structured context to be useful for documentation work.

Meanwhile, Claude’s context window keeps expanding and its native tools keep improving.

The ground keeps shifting while I’m building the bridge.

So I tried an MCP

My goal is to make it easier for developers on open source and small tools to draft useful documentation.

I built an MCP server for reformatters, a Python framework for converting weather datasets. It’s not meant to replace technical writers or documentation functions, but it should get people started.

In my last post, I was optimistic about it.

Here’s what actually happened:

Railway deployment wouldn’t bind to the right IP. Crash loops. But that was almost beside the point.
Claude Desktop only supports local stdio connections. I built an HTTP/SSE server for a client that can’t use HTTP. The Railway deployment was solving the wrong problem from the start.
The dataset tools had circular dependencies. They required the main reformatters package to be installed, which defeated the purpose of a separate knowledge repo.
Search tools returned nothing even when the content was right there. Tool registration worked. Retrieval didn’t.

The MCP server runs. The tools are registered. Claude thinks the knowledge base has good content. But the architecture was mismatched from the start: I built a remote-first HTTP server for clients that only work locally over stdio.

I had Claude Code verify the branch and document its findings. Its conclusion: MCP remote access isn’t mature enough for team-wide use. MCP requires infrastructure I don’t have the capacity (or desire) to maintain.

Claude Code eventually reached the Write the Docs-ready conclusion I’ve been arguing for, “we don’t need another repository, we just need better documentation.”

I used to write documentation. I still do, but I used to too.

BJJ Core Mechanics

The style of Brazilian jiu-jitsu has changed since it started getting popular in the US in the early 2000s.

Back then, though the tagline was about smaller practitioners beating stronger opponents, in practice, there was still a focus on heavy pressure. The “gentle art” was a little brutish.

Through the years, the way people “played” evolved, with new techniques catching people off guard and being used to win competitions, then catching on in gyms throughout the world.

That strategy, called “the meta,” becomes the new cool thing for a while, then people get good at countering or defending it, and it usually subsides or gives way to the next thing.

You’re not meant to abandon your entire game to chase only after the cool new thing.

Often, though the specific technique fizzles, some component remains and helps shape the new meta.

Berimbolos, x-guard, heel hook entries. They were all surprising at first, and now they’re just part of the system.

As a featherweight who’s highly proficient at pulling bottom side-control, the buggy choke was a gift. The problem is, pressure can still beat a buggy choke, and the real gift is reapplying the head-and-arm concept in other unexpected ways.

It’s fun to chase the meta, as long as you keep your “why” close at heart (and protect your neck).

Knee cuts, pressure passes, just standing up. They never left, and they still work.

It’s not that the techniques are necessarily fundamental, but that some concepts are.

Fundamental Concepts

MCP and skills might actually stick around, but I think they’re techniques that will get supplanted by more adaptive contexts and maybe a way to micro-train our tools. Things that would work out of the box.

The spiritual core of technical writing hasn’t changed much: know your audience.

Human readers are always the audience. That’s the same whether they’re accessing the content directly or through an AI tool.

That which was best practice before is still best practice now. Write things down, put them somewhere people can find them.

Make documentation a practice, and wherever you are in your practice, remember to keep practicing. Write things down even if they’re not perfect. Show them off even before you think they’re ready. Make it accessible.

I try to write accessible documentation, but who is accessibility for?

There are business cases for digital accessibility. When you write documentation with accessibility in mind, screen readers can navigate it, search engines can index it, and AI tools can parse and summarize it. The same practices that serve a person using a screen reader serve an LLM trying to extract meaning or translate content.

When you make things more accessible, like a curb cut, it helps people even outside the original intention. That’s not a coincidence, it’s fundamentals.

So go ahead, experiment with AI, build that MCP, try a buggy choke, and chase the meta. Just remember why.

AI is coming for my job. Maybe to my job.

Fri, 12 Dec 2025 00:00:00 GMT

While I was working on a pull request for a new Coder feature, there were a few times that Claude Code offered my own documentation or comment on a PR to answer questions I had.

It was a guess I made in a PR about the way a feature might work, and when I asked Claude Code to verify, it referred to the documentation. My documentation.

My job has always been to empower users to get stuff done smoothly and on their own.

Now my audience includes AI.

If humans and AI both rely on good documentation, how do I develop documentation and an information architecture that help both?

How I Use AI

I use Claude and Claude Code both at home and at work. On my phone, my chats with AI probably look a lot like most peoples’:

Is this poison ivy?
Which of these water bottles fit in my car’s cup holder?
What’s this broken part of our toilet called?
Is this rash poison ivy?

Claude Code might look a little different:

Help me turn my settings into dotfiles.
I have a Docusaurus site hosted through GitHub Pages. Let’s develop a plan to migrate it to Astro with Starlight.
When I ask you to help me work on documentation, remember the following…
Help me make a Claude Code plugin that helps you follow my standards for documentation.

For me, the great promise of AI is that it can make sense of piles of information that would take me hours to untangle and map out.

The current hype seems centered around how AI can take over tasks like research, software development, and documentation.

If AI has all the information, can it write the documentation for me?

AI Can Document Things; Humans Are Better at Writing Documentation

For a good example of this, explore DeepWiki, which “provides up-to-date documentation you can talk to, for every repo in the world.” It gives a comprehensive breakdown of a repository, but you won’t get concept, guides, steps, and examples. Right now, AI is excellent at documenting what exists in the way that it exists, but not as good at thinking about what a user will need.

When I write documentation, I take all the information I have from my own notes, from product managers, and the several threads from Slack in which someone said @Edward ☝️. I parse it all, following threads and connecting the dots.

With AI, I paste all the information into a window, tell it what we’re working on and direct the outline of documentation and examples. Claude lays out a plan, and if I’m using Claude Code, we dig deeper into the codebase or Git branch for the context I need.

Context, relationships, and information synthesis all help technical writers make better documentation. Usually we get that from subject matter experts (SME), by exploring codebases, or by being in every Slack channel and engineering standup ever.

If my AI tool has access to all of these, shouldn’t it be able to write the documentation itself?

It tries.

It can make a great outline, but it seems to have trouble navigating what kind of technical documentation to write.

AI is missing—at least for now—that magical blend of curiosity and empathy that helps technical writers anticipate their audience’s needs. It’s good at parsing content that is there, and it tries to imitate abductive reasoning as best as it can. Maybe that’s why it “hallucinates” technical content - it’s trying to guess, very much like I would, and it can get to the right answer, but it needs to be babysat, coaxed, coached, and led.

But while AI agents aren’t great at writing technical documentation (yet), they are a great aid.

Maybe aide is more appropriate. Claude Code is my SME, my always-at-hand assistant, my rubber duck, and regex expert.

How It Started / How It’s Going

I’m sure there will be advancements that feel threatening, and there will be companies that try to eschew a documentation and education function to “have someone else do it,” as there always are.

AI agents are becoming our technical analogues and companions, and the same way that some engineering teams are, technical writers will find ways that they augment and accelerate our work; not supplant us.

What if we can use this to make things better?

At Coder, as part of a larger effort to help other teams implement AI into their workflows, I created a knowledgebase that everyone could use to find answers and contribute documentation. This was before I learned about Model Context Protocol (MCP).

I want to make it easy for subject matter experts to share their knowledge, and for people who need it to find it.

Right now, I’m working on developing an MCP for an open source project that converts weather and climate datasets. As always, my goal is to develop a repeatable strategy. You can follow that repository to see how it goes.

That’s Documentation, and once I get it working, I’m looking forward to hearing about how you implement the concept, whether you learn it here or through a chat with your favorite AI.