Dachary Carey

Is Your llms.txt Already Stale?

Sun, 15 Mar 2026 23:00:00 -0500

You shipped your llms.txt. You linked to your docs pages. Maybe you even set up progressive disclosure with per-product files. You’re done, right?

Probably not. An llms.txt that was accurate when you launched it can silently drift out of sync with your actual documentation. New pages get added to the site but not to llms.txt. Old pages get removed or reorganized. The file becomes a stale index that points agents toward an incomplete picture of your docs, or worse, toward pages that no longer exist.

Agent Skill Mega Repo Woes

Fri, 13 Mar 2026 07:00:00 -0500

A month ago, I published an ecosystem-scale analysis of 673 Agent Skills from 41 repositories. I looked at Anthropic’s own skills, company-published collections from Microsoft and Stripe, community collections, and individual repos. The takeaway was that the ecosystem has real quality problems: 22% of skills fail structural validation, over half of all tokens are wasted on non-standard files, and broken links are everywhere.

Today, I saw a post on LinkedIn about antigravity-awesome-skills, a single mega repo that claims over 1,200 Agent Skills and has 23.7k GitHub stars. That star count makes it one of the most popular skill sources in the ecosystem. People are presumably cloning this repo and loading these skills into their agents.

Vibes are Out, Data is In

Thu, 12 Mar 2026 07:30:00 -0500

There’s a growing body of advice about how to write documentation for AI. Some of it is grounded in real observations. A lot of it is grounded in vibes: intuitions extrapolated from LLM research that was never designed to test documentation, recommendations passed around conference talks and blog posts until they calcify into “best practices,” and vendor guidance that may or may not reflect how agents actually behave in the wild. People aren’t wrong to form theories. But we’re skipping the step where we test those theories in the context that actually matters, and then building an industry playbook on top of the untested assumptions.

How to Measure Agent Web Traffic

Thu, 05 Mar 2026 21:00:00 -0500

After sharing my recent findings about how agents use docs with the folks at work, one of the first questions (from multiple people!) was: how do we measure the impact of these problems? Writ large, how do we know things like:

How many agents are trying to access our docs and running into issues?
How many docs pages are adversely impacted by these issues?
How can we tie agent access issues back to developer/product outcomes?

These are questions with many facets, and we’re still talking about what the answers might look like. But the first two problems seemed immediately tractable, so we can start digging into those things right away.

An Agent is More Than Its Brain

Mon, 02 Mar 2026 20:00:00 -0500

Apparently I live in the “agent” space now, so let’s talk about what’s inside an agent! I’ve been seeing conversations, and learning more myself, and have realized that maybe a lot of people haven’t stopped to think about what the component parts of an agent actually are. For the purposes of this article, I’m talking specifically about coding agents, but a lot of the bits and bobs are generalizable. And here’s why this matters: the model (“Opus 4.6,” “GPT-4o”) is just one piece. The same model can behave very differently depending on everything else around it.

Make Your Hugo Site Agent-Friendly

Sun, 01 Mar 2026 08:00:00 -0500

With all the writing I’ve been doing lately around agent-friendly docs, I decided that all new websites I set up will be agent-friendly from the beginning. I designed my two newest websites, the Agent-Friendly Documentation Spec and aeshift, to be agent-friendly from day one. Particularly with the spec, I thought that people might want to point agents at the spec, and I wanted to enable that. I pointed an agent at the spec (as local markdown on my filesystem) and built the sites to hit all the agent accessibility criteria. It didn’t add that much extra time to setting up each site, and it got even faster after I had a reference implementation I could point the agent at.

Case Study - 'upgrade-stripe' Agent Skill

Fri, 27 Feb 2026 08:00:00 -0500

When I did the research for my recent Agent Skill research paper, I took two approaches to trying to understand the impact of Skills in developer workflows: take a wide, zoomed-out look at Skills across different segments, verticals, and use cases, and take a closer look at a subset of those Skills where I had interesting theories I wanted to probe more closely. One of the skills I took a closer look at was the upgrade-stripe Skill. I had ideas about what I might find, and thought it might have implications for how other companies with multiple programming language SDKs should approach Skill development. What I found was not what I expected, but was arguably more interesting.

LLMs vs. Agents as Docs Consumers

Thu, 26 Feb 2026 08:00:00 -0500

I’ve been writing a lot about agents and docs lately, and one thing I keep bumping into in conversations is confusion about what “AI-friendly docs” actually means. Someone says their leadership has mandated that docs need to be optimized for AI, and when I ask what that means in practice, the answer is usually some variation of “I don’t know, they just said AI.” And honestly? I get it. “AI” is doing a lot of heavy lifting as a term right now, and it’s papering over a distinction that really matters if you’re trying to figure out what to actually do with your documentation.

Upskilling in the AI Age

Mon, 23 Feb 2026 23:00:00 -0500

I’ve been posting a lot of content lately and having a lot of conversations with people in various roles as a result. One message was from someone who I think was in a similar position to a lot of us right now. As I traded messages with them, I realized that because a lot of people are seeing my content right now, this is exactly when I need to write this article. So here was the question, and my answer:

Agent Web Fetch Spelunking

Thu, 19 Feb 2026 21:00:00 -0500

After posting about Agent-Friendly Docs, I got some very good questions that I wanted to dig into. I love the documentation community - such thinkers! So today, I present my spelunking in the agent Web Fetch tool. My goal was to figure out if I could provide a quick answer to whether agent platforms document the truncation limits of their various web fetch implementations, so documentarians can try to wrap our heads around what makes “agent-friendly docs.” First criteria: agent must be able to actually get the docs content.

Agent-Friendly Docs

Wed, 18 Feb 2026 21:00:00 -0500

Over the weekend, I spent about 10 hours working with Claude to manually validate 578 coding patterns across a range of languages and coding tasks for my Agent Skill Report. We had to deep dive into standard library docs, package-specific documentation, large enterprise docs, and personal blogs. My goal was to ensure that every API and configuration pattern I was using in a behavioral evaluation experiment reflected the current guidance from official sources. My learnings about agent docs access patterns were secondary to this project, but the results are a rich treasure trove of data that may inform how I use agents with docs in the future. As a technical writer who has worked on SaaS and developer docs for the last decade, honestly, my findings made me a little sad.

Agent Skill Analysis

Fri, 13 Feb 2026 10:00:00 -0500

Claude introduced Agent Skills in fall 2025, and they have quickly become the next hot thing in AI-assisted development. Agent Skills give your AI buddy just-in-time context to help it succeed with tasks that require specific domain expertise or resources. Anthropic released an Agent Skills specification, and other agentic platforms have been rushing to add support for it. In turn, individual developers are making their own Agent Skills, and companies are under pressure to provide official Agent Skills for customers to use in agentic development workflows.

Inside the Code Example Comparison APIs

Sat, 17 Jan 2026 10:00:00 -0500

In my last article, I wrote about why we designed a simplified testing framework approach to help technical writers test the code examples in our documentation. A major component of this is the unified Expect.that() comparison API we created to give writers a single entrypoint to validate our code examples. This API abstracts all of the field/value comparisons that validate that when we execute the code example we show in the documentation, it actually produces the output we show in the docs. We designed this system as a shortcut so writers wouldn’t have to learn individual assert syntax and do comprehensive testing for every code example they add to the docs.

Code Example Testing Redux - Designing Cross-Language Testing Infrastructure at Scale

Sun, 04 Jan 2026 23:00:00 +0000

I’ve written before about why you should test the code examples in your documentation and why your docs team should write the code examples. I’ve even written about how to test them and what you should test compared to engineering tests. But I wrote that content through a very specific lens; as a member of a team of developers who happened to be writing documentation. My team was already conversant with developer testing frameworks, tooling, and testing practices.

Diff Algorithm Spelunking

Mon, 29 Dec 2025 08:00:00 +0000

My wife has been using a word-diffing tool called dwdiff for years. It’s a ~25-year-old C program. Neither of us writes C. She made an attempt to understand it many years ago and port it to some other language she works in more regularly, but never finished the job. When she commented on using it in a pipeline with another Go tool I had written for her, I thought: “How hard could it be to make a modern version of this in Go?”

Audit - Conclusions

Sun, 07 Sep 2025 08:00:00 +0000

After a months-long code example audit process that included:

Aligning about definitions and types of code examples
Building out tooling to programmatically ingest code examples into a database
Creating queries to give us different views of the data
Refining our data and tracking capabilities based on evolving stakeholder requests

We had enough information to start drawing conclusions from the audit.

I did a preliminary share-out of some findings as a ~20 minute talk, but the real artifact of this process was the audit report. I wrote an 88-page report that included:

Audit - Slicing Code Example Data

Sat, 23 Aug 2025 08:00:00 +0000

With our code example audit data ingested into the database, we were no longer constrained to static analysis at the time of parsing the data. We had the freedom to analyze the data in a variety of different ways as we explored different theories and questions. I started with a simple count of code examples broken down by programming languages. As I explored the data, this evolved into 19 different queries (at the time of this writing) to break down the data in different ways.

Audit - Modeling Code Example Metadata

Sun, 27 Apr 2025 08:00:00 +0000

As we worked our way through this initial code example audit process, requirements emerged sporadically. At the core of this project, our department wanted to understand our code example content distribution and communicate about it to leadership. That became “count the code examples” by category and programming language. Even as we iterated on the tooling to perform the initial count, new requirements emerged. My team agreed that we couldn’t just take a static “count” approach - we needed to store information about our code examples in a database, so we could slice the data in whatever new way leadership wanted to break it down.

Audit - AI-Assisted Classification

Sun, 23 Mar 2025 13:00:00 +0000

With over 35,000 code examples, there’s no way our docs organization could afford for people to spend time manually assigning a category to each code example. Humans apply criteria selectively, too, which means we would categorize code examples inconsistently. When we started talking about an audit, I had recently written code examples using Go with a local LLM, Ollama, to perform some embedding generation and summarization tasks. I wondered if we could use Ollama to categorize our code examples, so I spent a few hours writing a proof-of-concept to test the idea. I iterated on the prompt until I got 90% accuracy with my test data, and called that “good enough” to validate the concept. It worked! We could use an AI to assign categories to the code examples.

Audit - How can we access the data?

Sun, 16 Mar 2025 13:00:00 +0000

Having defined categories to better quantify our code examples, and identified the data we wanted to track, we were ready to start the audit - right? One more technical design decision awaited us - how should we access the content we wanted to audit? Our directive was to “count the code examples in our documentation” with the ability to “break down counts by programming language.” Our documentation content source spans more than 50 git repositories, across tens of thousands of files, and with many different git branching schemes. So, how were we going to source the content we wanted to audit? And how were we going to access the data once we knew what content we wanted to audit?

Audit - What should we track?

Mon, 10 Mar 2025 00:19:00 +0000

Now that we had defined what we were going to count as a code example, we just needed to count them - right? As I worked on refining the brand-new-tooling we were building out to track this information, I realized we needed a lot more information about what we wanted to track, and how we might want to use the information, to make sure the tooling captured the right details in the right way. As I brainstormed, I wrote a four-page document trying to capture the details; there was a lot to consider. The points break down along these axes:

Audit - What is a Code Example?

Sun, 02 Mar 2025 13:00:00 +0000

When the Education AI team provided an initial count of code examples across our documentation corpus, broken down by programming language, the numbers were much higher than some members of the org expected. We apparently had tens of thousands of code examples, and nearly 9,000 of those were JavaScript. That couldn’t possibly be right, could it? And more importantly, because the number was so high, how could we break it down to be more meaningful?

Audit - Overview

Sun, 02 Mar 2025 00:11:00 +0000

My company uses a docs-as-code workflow. We have historically split our documentation by product, for reasons related to our platform’s implementation of table of contents and documentation/product versioning. This means we have documentation in a lot of different repositories (60+ by my last count), and the people who write and manage that documentation are split across four separate documentation teams. Each team has a different process for writing code examples. So for any given repository/product, the code examples may be created using a different process, and may contain widely variable content.

I wrote a macOS app!

Mon, 05 Aug 2024 00:01:35 +0000

Apparently writing Shattered Ring a few years ago whetted my appetite for useful tools that do what I want in the way I want. A mere month after releasing Shattered Ring, I started working on PR Focus: a macOS app that tracks pull requests across GitHub repositories. After more than two years of nights-and-weekends development, and several incarnations along the way, I have now released PR Focus on the Mac App Store!

Docs Consolidation Project - Month Two Check-In

Sun, 28 Jul 2024 15:00:00 -0500

My team documents a product that represents 9 different SDKs in 9 different programming languages. (And these things are not a 1:1 correlation!) To date, we have maintained 9 individual sets of SDK documentation - one for each SDK. I successfully made the case that we should consoldiate these individual doc sets into one single set of documentation, but now we have to do the work! This is the second in a series of posts that will continue until the project is complete. For the month one post, check out Docs Consolidation Project - One Month Check-In.

Docs Consolidation Project - One Month Check-In

Wed, 26 Jun 2024 15:00:00 -0500

My team documents a product that represents 9 different SDKs in 9 different programming languages. (And these things are not a 1:1 correlation!)

To date, we have maintained 9 individual sets of SDK documentation - one for each SDK. Our decision to consolidate these documentation sets probably warrants a separate blog post, so I’m making a mental note to do that soon. But for now, just know that we have decided to consoldiate these individual doc sets into one single set of documentation. It has a programming language selector on the page to let developers denote which version of the code example and relevant SDK details they want to view.

What to Test In Docs Code Examples

Sun, 11 Feb 2024 10:00:00 -0500

I wrote last month about how to test docs code examples. Now, let’s look at what to test in docs code examples.

Test the claims you make in docs
Use the APIs you document
Demonstrate common usage patterns and best practices
Figure out where you can safely omit boilerplate code

There are also a couple of “don’ts” when writing and testing docs code examples:

Don’t show “wrong” code
Don’t recreate comprehensive engineering tests for edge cases

Test the claims that you make in the docs

Developer documentation loses trust when the text makes assertions that are not correct. This can happen for a few different reasons:

How to Test Docs Code Examples

Fri, 12 Jan 2024 07:00:00 -0500

A few months ago, I wrote about why you should test docs code examples. Today, I’m going to look at how to test docs code examples.

The specifics may vary from team to team and tool to tool, but this is the broad shape of what this process looks like:

Write docs examples in unit test suites
Excerpt example code for inclusion in docs
Include example code in docs
Run docs tests in CI

In another post, I’ll dive deeper on what your docs code examples and tests should cover. For this topic, I’ll follow a code example from the unit test suite to publishing the docs.

Farewell, Critical Role

Sat, 09 Dec 2023 07:00:00 -0400

I have been a fan of the folks at Critical Role for many years. I’ve watched them since their Geek & Sundry days, when they were just a plucky group of friends live-streaming their home game at a few crappy folding tables in some Geek & Sundry lunchroom or break room or whatever it was. I have been so happy for their success. I have laughed, and cried, at the stories they’ve told. As they have grown and expanded into a corporation with their own production company, a publishing arm, lots of merch, and their own game systems in development, I have had such joy to see them grow into a company that sustains so many talented and passionate employees.

Hackathon Part 3 - Charts, Charts, Charts!

Wed, 15 Nov 2023 07:00:00 -0400

In this final installment in my hackathon series, let’s take a look at the MongoDB Charts I made from all the lovely data I’ve liberated from Google Sheets.

Starting with an Aggregate Dashboard

I had some ideas of what information I wanted to track, but nothing concrete. So I started out by playing with the different chart types available in MongoDB Charts.

When you start a new dashboard, Charts suggests a few default charts for you. I had no real idea what I wanted, so I started experimenting with the default charts. After generating a few, I decided that my first dashboard would be an aggregate dashboard. I wanted a quick snapshot to see data about the consumption metrics of the different SDKs.

Hackathon Part 2 - Modeling Documentation Metadata

Wed, 08 Nov 2023 07:00:00 -0400

Defining a data model

MongoDB is a document database. Developers love document databases because they make it easy to evolve a data model. But that wide-open flexibility can be a mixed blessing. It’s easy to add data without thinking very much about how you want to use it and what structure the data should have.

For my hackathon project, I had to consider what questions I wanted to ask about my data. Those questions would drive what structure my data should have. Before I got into importing a lot of data and making charts, I needed to nail down the data model.

Hackathon Part 1 - Out of Google Sheets and Into Atlas

Wed, 01 Nov 2023 12:00:00 -0400

One of my favorite things about working at MongoDB is that we do a hackathon once or twice a year. It’s a one-week extravaganza where we can work on PoCs, improve tooling, build skills, or try interesting projects. Some of my teammates have even built things during hackathon that have made it into the product! It’s great for making improvements and getting us to think creatively.

My idea

I’ve been thinking about how we could use analytics data to make more informed project decisions. As individual docs contributors, we don’t have access to Google Analytics. We do have a massive Google Sheets abomination that gets updated weekly. It contains information about all the docs properties owned by the DevEd team.

Benefits of Docs Writing Code Examples

Thu, 26 Oct 2023 12:00:00 -0400

A few weeks ago, I wrote about the benefits of testing the code examples in your documentation.

That article has sparked some interesting conversations. The topic kept turning to who should be writing the code examples.

I’m more convinced than ever that engineers should not write the code examples in your documentation. There are a lot of benefits to the way my team does it: the documentation team writes their own code examples.

Knowing When Docs Need Updates

Wed, 18 Oct 2023 12:00:00 -0400

As documentarians, our role doesn’t stop at creating new documentation. We’re also responsible for keeping existing documentation updated. If you’re part of a downstream team that is not involved in planning, finding out when the documentation needs updates can be challenging.

This is one part a process problem, and one part a people problem. You can solve process problems. People problems are harder.

Establish a Process to Communicate about Changes

The first step to finding out when documentation needs updates is establishing a process to communicate changes. It doesn’t have to be a heavy process. It can be something as simple as getting included on scope or technical design documents. It could be getting yourself invited to kickoff or planning meetings. Or it could be a Docs Needed flag on a Jira ticket.

Test Docs Code Examples

Tue, 10 Oct 2023 12:00:00 -0500

When I interviewed to join the Developer Education team at MongoDB, one thing really stood out to me: they maintain their documentation code examples in unit test suites. In fact, they wrote a tool, Bluehawk, to mark up and extract code snippets for use in documentation. They explained to me that this helped them ensure accuracy - the code was free of typos and would compile.

In the nearly three years since I joined the team, I’ve learned many reasons to maintain code examples in test suites. If you write documentation for developers, you should absolutely maintain tested code snippets for your docs. Here’s why.

Docs Readability Scoring

Fri, 10 Mar 2023 17:00:00 -0500

Experienced documentation writers know that grammar isn’t the only important aspect of documentation. Readability is a huge part of what makes documentation good. Readable documentation:

Is scannable, with lots of clear sections and bullet points.
Has short, simple sentences.
Uses common vocabulary and avoids jargon.

Why Readability is Important

The Nielsen Norman Group advises writers target an 8th grade reading level. Most technical writing comes in at 12th grade or higher. Documentarians sometimes use the excuse that it’s “technical writing” so higher is ok. This doesn’t consider that the density of documentation is an accessibility issue.

Welcome to my new, new home.

Sat, 19 Nov 2022 10:01:35 -0500

Why are we here? (Well, why is any of us here, really?)

No, not an existential question - a practical one! You’re here because you clicked a link from… somewhere. And want to know more about this Dachary person, or at least read something that I wrote.

The current era is late 2022. Twitter is in the process of imploding. I fled there months ago, for sunny new shores on a Mastodon server. A new, massive influx of Twitter visitors heralds the end of a new age, and the beginning of a new?

I wrote a… best-selling iOS app?

Mon, 14 Mar 2022 15:01:35 +0300

Hey! Remember that time I wrote an iOS app to keep track of my Elden Ring and D&D play through details, and released it to the App Store?

Why, I remember it like it was just last week…

Turns out, when you email industry-specific news sources with topical news that has an interesting angle, some of them will write about your stuff.

My little hobby app, Shattered Ring, has been featured on a ton of video game news sites, including:

I wrote an iOS app!

Wed, 09 Mar 2022 15:01:35 +0300

I’ve had a handful of iOS app ideas in the past few years that I could never quite figure out how to turn into reality. I found it frustrating, though, because I really want to use the apps I’ve had ideas for. Finally, I’ve had enough practice with smaller projects that I managed to turn an idea into reality: my first iOS app is live on the App Store!

May I present: Shattered Ring, the Elden Ring task tracker you didn’t know you needed.

CLI tool version complications

Thu, 20 May 2021 15:01:35 +0300

I’ve been playing around with different versions of the realm-cli for some documentation projects. That means installing and uninstalling various versions via NPM. I kept getting tripped up on this complication so I’m documenting it here in case other folks find it helpful.

NPM uninstall

Using npm uninstall is simple, right? Just run it with the name of the package you want to uninstall, and maybe pass a few flags like -g if needed, and the package is gone.

Docs-as-code workflow: the missing link; a collaboration tool

Sat, 23 May 2020 15:01:35 +0300

Docs as code is a technical documentation movement to use the same tools that developers use in the documentation workflow. It’s a great way to enable collaboration with developers, and now that I’ve been doing it for more than a year, I can’t imagine writing documentation for developers, with developers in any other toolchain. But one thing is missing from most docs-as-code workflows: a collaboration tool to easily share the work and solicit feedback.

Learning to code: redux

Tue, 19 May 2020 15:01:35 +0300

A little over a year ago, I wrote here about how I was learning Swift because there are a couple of apps I want to write. I’ve gone through a few courses online, and had started working through an Everyone Can Code book: AP Computer Science Principles with Swift. I was making good progress, had done the data modeling for my “main” app, but then got a little overwhelmed with the idea of actually starting it. Like, how does a n00b sit down and begin writing an app for the first time?

What does coffee taste like?

Wed, 15 Jan 2020 15:01:35 +0300

Or why I love good coffee, and how you can learn to love it, too.

TL;DR: Check out this coffee tasting wheel from Counter Culture Coffee - there’s more than bitter/burnt in coffee flavors!

ZOMG COFFEE

I’m a coffee lover. It’s the second fact I put in my about page, after “I write stuff.” It’s a big part of my core identity.

I didn’t start out liking coffee. My grandma let me take a sip of her black Folgers instant coffee when I was a wee lass, and I hated it. I went through my teens and early twenties convinced I’d hate it forever; I’d try it every now and again, but it just tasted bitter and gross to me. Ugh. No way.

My social media withdrawal experiment

Wed, 09 Oct 2019 15:01:35 +0300

In the past few years, I’ve gradually trimmed down my social media exposure. In the past month, I’ve eliminated social media almost entirely. Why take such a drastic step, and how do I feel about it now?

Making the easy cut

It started with Twitter. Every time I opened it, I ran across posts that made me feel depressed or angry or frustrated; usually some combination of the above. Not only was I wasting time there, but it was making me feel some very unpleasant emotions.

How home automation has made me a more productive remote employee

Fri, 04 Oct 2019 15:01:35 +0300

I’ve been working remotely since 2007. Along the way, I’ve learned a few things about how my workspace impacts my productivity. Home automation has enabled subtle improvements to my life and productivity as a remote employee - and subtle improvements can have big impacts.

Boundaries

When I first started out working remotely, I was in my mid-20s and every day was a hustle. I didn’t have any family obligations, and my social life was slow at the time. I worked from anywhere, anytime. I’d work from my couch at 2am. I’d work from my desk during the day. I’d wake up and check/respond to email from bed. I’d walk to a coffee shop and work.

My vacation rafting misadventure

Tue, 20 Aug 2019 15:01:35 +0300

Or that time I accidentally body-surfed a Class V rapid on the Penobscot River in Maine.

Trigger warning: discussion of near-drowning, death.

The day so far…

My husband and I were spending the week with four friends at a rented lake house in Lincoln, Maine. The friends and I had done a rafting trip the prior year on the Androscoggin River in New Hampshire with ELC Outdoors, and had really enjoyed it - in all it’s mild Class I-II glory. It was mostly a float/paddle down the river, with a few mild rapid sections to get us wet and get the heart rate up. I had been bummed that the hubby missed that trip, and looked forward to getting him into rafting on this outing.

Investing in good equipment

Thu, 08 Aug 2019 15:01:35 +0300

A younger, more innocent me bought a 13" mid-2014 MacBook Pro on closeout in early 2015. My main tasks for my computer at that time were writing documents in word processors (Pages) and using CMSs to create and publish content. I thought I might do some light video editing of travel videos for Corporate Runaways, but didn’t have much need or desire for a powerhouse machine. I had an external monitor for additional screen real estate, and mostly used the laptop screen for reference material.

Choosing the best writing tool

Fri, 12 Jul 2019 15:01:35 +0300

In my recent technical writing job search and interviewing process, I’ve encountered a lot of discussion around tooling. I always ask about the toolchain for a position I’m considering, and I’m happy to talk tools all day long. But the truth is, I’m tool agnostic. My questions about toolchain aren’t about deciding if you use a tool I like; they’re about discovering the maturity of your process.

That’s because there is no such thing as a one-size-fits-all writing tool.

Real talk: freelance/contract writing

Wed, 12 Jun 2019 15:01:35 +0300

Someone in the Write the Docs Slack was asking about things to consider as she pondered transitioning to a freelance/contract technical writing career, and I have Thoughts to share:

Benefits and administrative overhead

Freelance/contract typically means 1099, which means no benefits - no insurance, no matching 401(k), no PTO, and you do your own tax withholding and paying. These things have a real dollar value, so it’s worthwhile to consider what your rate needs to be to make up for the cost of losing those benefits.

Learning to code

Wed, 06 Mar 2019 15:01:35 +0300

There are a couple of apps I’ve been wanting to write, so the time has come to learn to code! Unsurprisingly, this makes hubby happy, as now I can more readily empathize with the geeky coding plights of a senior web dev.

It’s actually been pretty interesting, so far.

I first taught myself to code in Basic when I was 12 or 13 on a Commodore 128 computer; programs were on floppy disks then, the 5 1/4" kind. I had a handful of programs that came with the computer, which my family bought used for $400; a lot of money in the early ’90s. (They’d spend $999 on my next computer in the mid-’90s, a Packard Bell Pentium 75mHz machine, running Windows 3.11. I was a lucky little kid.)

The downside of works-for-hire, NDAs and dead links

Thu, 21 Feb 2019 15:01:35 +0300

I’m applying for jobs again, which brings me once again to the Hell that is “provide links to your work.”

There are three reasons that’s not a simple request, and I dread this question:

I’ve written literally thousands of pieces of content as works-for-hire. This means that I do not retain rights to those works. In many cases, they are posted under someone else’s name. They may contain proprietary information. My best pieces have been written as works-for-hire, which means I cannot share those pieces with potential employers/clients. It’s a bummer.
NDAs. In the corporate world, NDAs are common. I’ve spent years of my life writing for clients with literally nothing to show for my effort, because those works have been protected by NDAs. When I apply with corporate clients, or clients who want to see my business or technical writing content, I simply can’t show samples because that content is restricted under NDAs.
Contrary to popular belief, the web is not forever. From 2007 to 2016 or so, I maintained a freelance writing website with portfolio links to articles I had written. It was awesome, because I could simply link clients to relevant content when interviewing. But businesses went out of business; people changed web hosts and URLs, and much of that portfolio turned into broken links. So I took it down, because curating and maintaining a working list became a major time sink.

So now, when I fill out forms asking for links to my prior work, I basically end up saying ad infinitum “I can’t provide working links, but I can send you some PDFs.” Or “I can’t provide samples because of NDAs and works-for-hire, but trust me, I’ve written a ton in that industry and it was really good stuff.”

Looking for a new (meaningful) writing gig

Tue, 28 Aug 2018 15:01:35 +0300

At the beginning of August, I said farewell to the company where I’ve been contracting for the past two years. I worked with a great team, but I’d gotten burned out and it was time to take a break and then look at what I want to do next.

My plan had been to focus on publishing and doing my own writing full-time whenever I left that contract gig, but… I haven’t built up the publishing to the point where it can pay all the bills yet, and frankly, it feels a little frivolous to me at this moment in time.

Unnecessarily gendered language

Sun, 08 Apr 2018 15:01:35 +0300

I was chatting with someone the other day, and caught myself using “guys” - as in, “you guys” - when talking with a woman about her relationship with her wife. I’ve been sensitive to using that word for years now, and I stopped myself, explained that it was one of those unfortunate verbal habits I’ve been trying to break, and re-framed the inquiry with “you ladies.”

This is one of MANY examples of a time I’ve gotten frustrated lately with how unnecessarily gendered our language is.

To business card, or not to business card

Sat, 07 Apr 2018 15:01:35 +0300

Silly thing, I know… but I don’t have business cards anymore. I’ve had so many business cards over the years, in various incarnations, that when I made the decision to stop promoting my freelance career, I abandoned my old cards and made an intentional decision not to get new ones printed. I didn’t want cards for Bright Little Light Press yet, since I’m basically a one-woman house and imposter syndrome and all that stuff. I figured I’d probably get some printed eventually when we get bigger and I want to start accepting submissions, potentially hiring, etc. And I didn’t feel that personal cards were particularly relevant, as I wasn’t promoting my freelance career anymore.

My strange caffeine detox journey

Sun, 25 Jun 2017 15:01:35 +0300

If you know me at all, you know I’m a devoted coffee snob. I have an AeroPress at home and a second one at the office where I’ve been contracting for almost a year. I have not one, but two expensive burr grinders so I can always brew from fresh beans (one at home, one at the office). I temp the water before I brew. (Different beans extract ideally at different temps - I generally prefer anywhere from 85C to 95C depending on the bean, but 92C seems to be about my sweet spot.) And I buy rather expensive single-source beans from a local roaster.

Protecting your digital empire

Sun, 18 Jun 2017 15:01:35 +0300

After some of the conversations I’ve seen lately about backup strategies, I have been reminded that I’m not on my A-game when it comes to backing up my digital assets. It’s not just manuscripts; it’s the book covers, ad images, videos, podcasts and everything else related to the publishing empire. I’ve had bits and pieces backed up here and there, but not a comprehensive strategy.

So hubby and I have just splurged on a Synology (a raid array storage device with redundant drives to back up computers, so even if our computer dies and our backup fails, there’s another backup) and we’ll be syncing it with Backblaze for offsite storage.

Some days are harder than others

Sun, 07 May 2017 15:01:35 +0300

Some days, being a writer is hard.

You sit in a room, by yourself, pouring words out onto a screen through a keyboard. (Or a typewriter/pen onto paper, if you’re old school.)

You create worlds. They could be beautiful, or horrible, depending on what’s going on in your life. Your heroes could have wonderful adventures, or face Sisyphean struggles - or both within the span of a single story.

You have entire conversations in your head. There could be whole days when you don’t interact with another human being - you’re just alone with the people who have sprung from your mind.

Beauty and the Beast: Why We Don’t Mess with a Classic

Sun, 02 Apr 2017 15:01:35 +0300

I went to see the Beauty and the Beast live action movie over the weekend.

I have opinions.

To give you a little backstory…

Beauty and the Beast is one of my favorite stories of all time. It caught my imagination at a young and impressionable age, and it has stuck with me relentlessly into adulthood. I love all versions of it. I love the classic Disney cartoon. I love Robin McKinley’s Beauty. I love Robin McKinley’s Rose Daughter. I even love Sheri Tepper’s darker, grittier Beauty. In fact, I’ve got a soft spot for fairy tale retellings of all sorts, but Beauty and the Beast remains one of my all-time favorites. I’ve read somewhere between a half dozen and a dozen different book-length versions of this story.

About

Mon, 01 Jan 0001 00:00:00 +0000

A Few Words About Me

Hello. I’m Dachary Carey. I build things that help developers succeed.

By day, I work on developer education and documentation infrastructure at MongoDB - building tools that ensure code examples actually work, testing frameworks that catch errors before developers encounter them, and processes that keep documentation accurate at scale.

By night (and weekends), I build apps. I’ve shipped PR Focus, a macOS app for managing pull request reviews, and I’m working on a few iOS apps that scratch various personal itches. I write Go libraries for semantic diffing, CLI tools for documentation auditing, and whatever else solves a problem I’m having.

AI & Agent Research

Mon, 01 Jan 0001 00:00:00 +0000

I research how AI agents work, how they consume information, and how the ecosystems around them are evolving. This page collects that work in one place. For my documentation background, see Documentation & Developer Education. For my programming projects, see Programming.

Talks & Interviews

Why AI Agents Struggle with Modern Documentation (YouTube, 2026) - Interview covering how agents access documentation in real time and the failure modes most docs teams don’t know about.

Specifications & Standards

Agent-Friendly Documentation Spec

A specification defining 21 checks across 8 categories for evaluating how well a documentation site serves AI agent consumers. Covers llms.txt discovery, markdown availability, page size, content structure, URL stability, and more. Based on real-world agent access patterns I’ve been researching since late 2025.

Contact

Mon, 01 Jan 0001 00:00:00 +0000

Get in Touch

Need to contact me?

I’m intermittently active on Mastodon, so you can try me there as @dachary@dacharycarey.social.

If you’re curious about my code stuff, you can find me as dacharyc on GitHub. Although most of my recent personal projects are in private repos as I’m releasing those as paid apps.

If you’ve got a longer message, drop me a line via this contact form, although I’ve gotten worse at answering emails in the past few years.

Documentation & Developer Education

Mon, 01 Jan 0001 00:00:00 +0000

I’ve spent nine years building documentation systems, testing infrastructure, and creating developer education content. This page covers that work - for my programming projects, see Programming.

Agent-Friendly Documentation

I’ve been researching how AI agents consume documentation and building tools to help docs teams optimize for this new access pattern. Agents fetch docs in real time, but face constraints that human readers don’t: truncation limits, inability to render JavaScript, unreliable redirect handling, and more. Most docs teams are being told to “make docs AI-friendly” without a clear picture of what that means in practice.

Programming

Mon, 01 Jan 0001 00:00:00 +0000

I build tools that solve problems I encounter in my own workflow - whether that’s managing pull requests across repositories, getting readable diff output, or ensuring code examples actually work.

Developer Tools & Libraries

Tools I’ve built to solve developer workflow problems.

tokendiff

A Go library and CLI for human-readable, token-level diffing.

Standard diff tools optimize for minimal edit distance, but often produce output that’s hard for humans to parse - fragmenting changes across common words like “the” or “for.” tokendiff uses a histogram-based algorithm with heuristics tuned for readability.

Resume

Mon, 01 Jan 0001 00:00:00 +0000

Dachary Carey

Developer Experience | Documentation Infrastructure | Ecosystem Analysis

GitHub: dacharyc | LinkedIn: dachary | Web: dacharycarey.com

Download PDF version

Summary

I build tools, infrastructure, and research that help developers succeed. My work combines nearly two decades of professional writing with software engineering, giving me an unusual ability to move between building systems and communicating about them clearly.

At MongoDB, I design testing frameworks and audit tooling for code example quality across 40+ documentation projects. Independently, I conduct ecosystem-scale research on AI agent tooling, build developer tools in Go and Swift, and ship apps on the Mac App Store and iOS App Store.

Dachary Carey

Is Your llms.txt Already Stale?

Agent Skill Mega Repo Woes

Vibes are Out, Data is In

How to Measure Agent Web Traffic

An Agent is More Than Its Brain

Make Your Hugo Site Agent-Friendly

Case Study - 'upgrade-stripe' Agent Skill

LLMs vs. Agents as Docs Consumers

Upskilling in the AI Age

Agent Web Fetch Spelunking

Agent-Friendly Docs

Contents

Agent Skill Analysis

Inside the Code Example Comparison APIs

Code Example Testing Redux - Designing Cross-Language Testing Infrastructure at Scale

Diff Algorithm Spelunking

Audit - Conclusions

Audit - Slicing Code Example Data

Audit - Modeling Code Example Metadata

Audit - AI-Assisted Classification

Audit - How can we access the data?

Audit - What should we track?

Audit - What is a Code Example?

Audit - Overview

I wrote a macOS app!

Docs Consolidation Project - Month Two Check-In

Docs Consolidation Project - One Month Check-In

What to Test In Docs Code Examples

Test the claims that you make in the docs

How to Test Docs Code Examples

Farewell, Critical Role

Hackathon Part 3 - Charts, Charts, Charts!

Starting with an Aggregate Dashboard

Hackathon Part 2 - Modeling Documentation Metadata

Defining a data model

Hackathon Part 1 - Out of Google Sheets and Into Atlas

My idea

Benefits of Docs Writing Code Examples

Knowing When Docs Need Updates

Establish a Process to Communicate about Changes

Test Docs Code Examples

Docs Readability Scoring

Why Readability is Important

Welcome to my new, new home.

I wrote a… best-selling iOS app?

I wrote an iOS app!

CLI tool version complications

NPM uninstall

Docs-as-code workflow: the missing link; a collaboration tool

Learning to code: redux

What does coffee taste like?

ZOMG COFFEE

My social media withdrawal experiment

Making the easy cut

How home automation has made me a more productive remote employee

Boundaries

My vacation rafting misadventure

The day so far…

Investing in good equipment

Choosing the best writing tool

Real talk: freelance/contract writing

Benefits and administrative overhead

Learning to code

The downside of works-for-hire, NDAs and dead links

Looking for a new (meaningful) writing gig

Unnecessarily gendered language

To business card, or not to business card

My strange caffeine detox journey

Protecting your digital empire

Some days are harder than others

Beauty and the Beast: Why We Don’t Mess with a Classic

About

A Few Words About Me

AI & Agent Research

Talks & Interviews

Specifications & Standards

Agent-Friendly Documentation Spec

Contact

Get in Touch