Edward Angert | Blog

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 2,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 2,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.