Microblog on Dachary Carey

Last vacation post - I've liberated my content from LinkedIn

Sun, 18 Oct 2026 18:38:42 -0400

Last vacation post... I have liberated my content from LinkedIn!

For ages, I've been lamenting LinkedIn's lack of an API to search my content. I've written a lot of useful stuff, but I haven't been able to have my agents look at it or do anything with it outside of LinkedIn's platform. So now I'm microblogging on my website first, and cross-posting to LinkedIn!

If you go to the front page of my website, you'll now see a "Microblog" section on the right that contains all of the relevant LinkedIn posts I've made over the last five or so years.

The microblog has a separate RSS feed, so if you want to watch just my LinkedIn-type content, or watch it in addition to my full articles, you can! And you don't have to worry about missing things that LinkedIn's algorithm just doesn't tell you about.

Every post has a cross-link to its LinkedIn version, so if you want to react or leave comments, you can click through and do so.

I've backfilled it by requesting an export of my data from LinkedIn, and I had Claude help me curate them to omit anything that's specific to events I've attended or other things that aren't really relevant outside of a time-based feed, but to keep the long-term content.

I've also added handling for things like LinkedIn's custom URL links, images, and people's full names, which might be appropriate on LinkedIn but maybe not on my personal website.

If this sounds like something you'd like to do, too, I've got an article draft scaffolded about how I did this so you could do something similar! I'll try to get it published soon-ish.

I've been getting a lot of messages lately from people

Sun, 18 Oct 2026 14:25:11 -0400

I've been getting a lot of messages lately from people asking me to post somewhere about their cool thing they have built on top of AFDocs. Rather than handling all of those as one-off requests, I've added a "Powered by AFDocs" page to the site!

If you have created a thing that uses AFDocs, and it's publicly available and attributes AFDocs, feel free to PR to add your thing to the page.

It's pretty neat to see a roundup of all the cool things people are building 🎉

This week's 'what I'm thinking about this week'

Fri, 16 Oct 2026 18:32:40 -0400

This week's "what I'm thinking about this week" isn't about work, since I had the week off work! (Well, at least not directly.)

I did get some downtime in, but if you know me, you also know that when I'm not working I'm working on personal projects. So much to do, so little time. So this week I've been focused on a new pipeline to surface agent experience-related topics from across the industry.

This uses my new topicsleuth library to analyze content I feed it from arXiv, product releases, industry bloggers and reporters, and other sources I care about. It uses domain-specific rubrics to identify agent experience-related content and assess how the content relates to AX topics I'm tracking, or propose new ones.

Then, create a daily briefing that surfaces relevant content for me from high-value topics. And a weekly briefing that helps me track changes over time, and make some forward-looking projections about where the industry is going. Because this is a single-user project, I can be very specific - the screenshot below is one of the topics from today's run, with recommendations that the model made for me based on what it thinks I care about. (It's pretty good!)

It can help me track changes by vendor, can help me spot consolidation or bifurcation in the industry, and spot emerging trends or identify topics that are fading in importance. And because I've been tracking related content since I started my research pipeline in March, I was able to backfill this new project with thousands of pieces of content so I can already see changes over time.

🤞 this helps me keep an eye on emerging and maturing trends in agent experience as this new field is being defined. (And yes, it's wild and amusing to see my own content feeding these topics, too!)

My new lib is out! This one contains the logic that runs

Thu, 15 Oct 2026 15:17:04 -0400

My new lib is out! This one contains the logic that runs my research pipeline. To use it, you find content you're interested in and feed each piece of content through the lib. The lib:

Uses vector embeddings to pull semantically-related topics from a vector store
Passes the similar topics and the piece of content to an LLM and asks it to say whether the content is related to any similar topics, or warrants a new topic
For each connection, it asks whether the content supports a topic, extends a topic, contradicts a topic, or marks a shift in the topic (i.e. something that was previously only research is now a feature shipped in a product)
You can optionally use a second model - either an LLM or a decision model like Jev - to provide a second opinion if a new topic is being proposed
It also tracks topic lifecycles, noting whether a topic is emerging, active, mature, fading, or dormant

It comes with the machinery to tune results based on how well the LLM is identifying content relative to your topics. I have found that it worked better with an earlier version of Opus, but a newer version was more likely to propose new topics (new topic creation went from 20% to ~40+%). So best results may require making some tweaks until the topic creation and assignment matches your human judgment, and you may need to tune things as parts of your pipeline change.

This has been working well for me in a pipeline for ~7 months, but I've broken it out into a lib because I want to use it in a couple of new ways/projects. If you have any need to watch how topics emerge, grow, and change over time, you may find it useful - look for topicsleuth on PyPI or I'll throw a link to the GitHub repo in the comments.

Week 12 at new job, and here's what I'm thinking about

Fri, 09 Oct 2026 10:35:06 -0400

Week 12 at new job, and here's what I'm thinking about: how can we leverage work other people are already doing to accelerate our understanding of agent experience?

Attending the internal agent summit this week gave me a lot of great glimpses into what other teams are working on. Some of it is directly relevant to problems I'm watching product teams struggle with, such as how do you set up a realistic environment to run evals, or how do you create a realistic task set? Other people are working on helping partners and enterprises answer these questions, so how can I leverage that work for our internal product teams?

I don't know the answer yet, but it's something I need to make time to dig into.

This is also somewhat related to how I keep up with what people across the industry are doing. I've been running an AI news gathering and filtering pipeline for my personal use since March. Last weekend, I started redesigning this to bring in more sources, drop some of the work I had envisioned that never materialized, and add lenses to help me focus on agent experience. This is going to involve extracting some of my topic analysis and tracking code to a shared library, which I'm hoping to release in the next few weeks.

As the industry keeps moving, I need to keep iterating on both how I can track that progress and how I can bring what applies into both my work and personal projects.

Also, time flies! I've been here nearly 90 days so I think I'll stop the "week number" and "new job" references but keep posting weekly what I'm thinking about. It has been useful for me in spurring conversations with folks, and I hope it's helping other people think about how we can shape a shared understanding of what agents need and how we can help them discover and use products more effectively.

Protip

Thu, 08 Oct 2026 12:44:41 -0400

Protip: if I am in a meeting with you, and you’re showing off your very cool agent thing, I am going to ask how you’re testing it.

Just plan for this and be ready to talk to me about it.

If you’re testing it in a meaningful way, I will be so impressed and will want to learn from your techniques.

Please impress me… please…

I got a chance to give a lightning talk today at an internal company summit…

Tue, 06 Oct 2026 22:29:42 -0400

I got a chance to give a lightning talk today at an internal company summit around agent things. A few things stand out from both my session and other sessions today:

Holy heck is it cool to be working at NVIDIA at this moment in time. Lots of people are working on lots of very cool agent things. It’s really inspiring to see what other people are working on, and get ideas and potential collab for the things I’m working on. 🤩
Agents are super cool but there are also a lot of hard engineering problems around all this stuff. It really is a generational shift in software engineering, and figuring out new ways to apply familiar patterns in this new paradigm. And availability of tokens does not solve the hard problems. That takes work.
Even in this room of very smart people working on very cool things, the thing I am working on remains a hard problem. Nobody else has a magic fix that makes my hard problem easy. That is validating in that I think my work is worthwhile and justified - I’m not wasting effort on something someone else has an easy fix for. But also a little sad because an easy fix would let me say “ok, THIS is solved, let me go work on the other 999,999 problems I find interesting.” 🤣

Awesome day. Very curious what else I’ll learn about during day two tomorrow 😁

The number of AI-written research papers on arXiv these days really makes me sad

Tue, 06 Oct 2026 08:14:07 -0400

The number of AI-written research papers on arXiv these days really makes me sad 😢

The quality of the content varies wildly; some people edit judiciously so it’s more the phrasing that makes me cringe, but others just accept the AI spew whole cloth which means I have to wade through mountains and mountains of repetitive and duplicative content to pull out the actual points.

But more critically, after messing around for months with an AI writing pipeline, I never did manage to get it to a state where factual correctness was satisfactory. Knowing how much effort I put into that, and how many factual issues were present even after every strategy I employed to mitigate it, I have a hard time taking any of these AI-written papers seriously. If the authors can’t take the time to edit their papers I have no reason to think they took the time fact check the volume of assertions these papers make, or the underlying data they probably also generated with AI 😢

Week 11 at New Job, and here's what Im thinking about

Fri, 02 Oct 2026 08:59:11 -0400

Week 11 at New Job, and here's what Im thinking about: how do I scale myself and share learnings effectively across a company with hundreds of products and 40k+ employees?

I can't be everywhere all at once. I have a multi-year research backlog if I'm the only one doing it. It would probably take me 10 years to work with every product team individually to help them learn about agent experience. Since I can't clone myself, I've gotta figure out how to scale. Here's what I'm thinking so far:

I'm putting together a 50-500 level course to help my colleagues go from 0 eval experience to performing ablations and other types of studies
I'm preparing a newsletter strategy to share agent experience learnings from experiments we run
I've been running a weekly forum for people to come together and share their learnings, which I am recording and planning to turn into reusable patterns and best practices
I'm speaking at a summit next week to raise awareness of the specific eval shape we've seen product teams struggling with, partially to let people know they can be doing this and partially to solicit feedback on how we might help product teams upskill around this
I'm drafting self-serve enablement materials which will live in our internal information-sharing spots, and may eventually turn into tooling or other artifacts to help teams upskill on their own time, without us having to be in the loop for teams that can't wait until we have capacity
I'm working with my teammates to draft a landing page for this work with more details so people can learn about it without needing to have a meeting with us
I've written down a running doc of research ideas, why they matter, and what the research methodology might look like, so people who are interested in any specific questions can pick up a task and run with it

What have I missed? For other folks who have run into this problem, I would welcome any tips you have!

The more I dig into how agents fail on tasks, the more I find about how product…

Thu, 01 Oct 2026 08:43:22 -0400

The more I dig into how agents fail on tasks, the more I find about how product surfaces need to change to reflect this new consumer. Let me tell you about two recent examples:

First, version information in docs. I was able to reproduce agent failures consistently related to missing version information, on multiple axes. When humans go to a versioned documentation page, they typically see version information on the page. Maybe it's interpolated into the page title or header, and usually there is a version switcher that lets humans select a different version of the docs.

Agents don't see that. When agents hit the markdown versions of the page, like Claude Code requests markdown by default through content negotiation, if the markdown content doesn't include the version information, Claude doesn't see it. And most sites I've seen are not generating version information into the markdown. Here's what this failure looks like in practice:

Claude sees an install page that shows how to pin a version, which includes v0.5.1. Claude installs v0.5.1. But the product has moved on to v0.6.0. Except Claude doesn't see anything about v0.6.0 on the page.
Claude looks up documentation for specific functionality. That documentation reflects functionality in v0.6.0, but it doesn't say so on the page. Claude tries to use it, but the functionality doesn't exist in the version of the product it's using, which is behind.
This is where I've seen it diverge: Claude either tries to build its own version of the feature as written without mentioning anything to the user, or tells the user that the functionality is absent and it can't do the requested task, or implements something completely different which it may or may not call out to the user. I have never yet seen the agent recognize that the version is behind, or even check GitHub to figure out the discrepancy, even when the product is public.

So missing version information bites agents in multiple ways: it can cause the agent to install old or outdated products even when looking at up-to-date documentation, or it can cause the agent to reach for functionality that doesn't match the installed version of the software.

A second example is related to patterns that exist in training data, and how agents can confidently invent things that don't exist. I was working with a product that has a start and a status command. Claude retrieved documentation for the product, which uses its web fetch tool with a smaller model, Haiku, summarizing page content for the orchestrator model - in my case, Opus 5.5. Haiku tells Opus that the product has a start, status, and stop command.

The product doesn't have a stop command. It uses ctrl + c to stop. But Haiku is a small model, and there is enough start, status, stop patterns in its training data that it makes up the plausible command that doesn't exist. So my open question is - should the product add a stop command? 🤔

Can I just say how cool it is to

Wed, 30 Sep 2026 17:37:46 -0400

Can I just say how cool it is to:

Ask an agent to do a task
Hand it a link to a relevant docs page
See it observe the in-page directive pointing to llms.txt
Watch it pull the file, and then proceed to pull like 4 other relevant docs pages to answer questions it has

It feels so awesome to watch my tools work better/more effectively and know I played a part in shaping that outcome 🎉

A thing I have been seeing is that it’s really hard for product teams to come…

Wed, 30 Sep 2026 08:33:01 -0400

A thing I have been seeing is that it’s really hard for product teams to come up with realistic user prompts for running evals.

I have been leaning on traditional developer experience artifacts to help with that. If you’ve got personas, jobs-to-be-done, and user journeys for your product, you can pick a persona, a job, and potentially a journey stage to create realistic prompts for that user. So developer experience is still the right starting point for agent experience when it comes to writing eval prompts.

Another thing you can do is use public GitHub projects to derive eval prompts. If you’re tracking public projects where your product is used, you can look at PRs that have integrated or configured your product, and those are real user jobs to be done that you can derive prompts from. Public GitHub data carries a cheating risk, though, in that agents with Internet access can go look at the actual completed work on GitHub and provide an answer rather than reasoning about it.

If you run evals to understand how agents use your products, how do you derive prompts? Does anyone have any other good tips or techniques to share?

AFDocs had a busy weekend; two new releases for documentation teams who want to…

Mon, 28 Sep 2026 08:44:02 -0400

AFDocs had a busy weekend; two new releases for documentation teams who want to check their docs for agent-friendliness:

v0.21.0 is a bug fix and non-breaking enhancement release; thank you to @JakeSCahill for reporting issues and @danielcalvolopez for a PR to emit progress notifications
v0.22.x is a breaking release that introduces 5 new checks, bringing it up to spec v0.6.0, which changes scoring and may require sites to do new work to improve agent-friendliness

Notably, one of the new checks calls for markdown versions of pages to contain absolute links instead of relative. When migrating to v0.22.0, I had to update several of my sites that only contained relative links. This makes the markdown more portable, and solves several cases where agents could fail to construct the correct URL if it needs to load a related page.

Because v0.22.0 is a breaking change, I've added a new "Upgrading to v0.22.0" page to the docs.

What happens when you run another coding agent through a benchmark designed to…

Sat, 26 Sep 2026 15:32:54 -0400

What happens when you run another coding agent through a benchmark designed to detect ways in which divergence from the Agent Skills specification breaks the cross-platform portability promise?

You find more broken promises 😢

I've added GitHub Copilot CLI support to agentsummons, agentminutes, skillxp - and finally to the Agent Skill Implementation benchmark group. I'm now up to testing with 4 coding agent harnesses, have added 5 new checks, and many of the checks now expose more different ways harnesses have implemented something, which breaks cross-platform portability in ways I hadn't observed yet.

New on the site:

A GitHub Copilot CLI platform report, and updates to the cross-platform comparison tables
5 new checks
Guidance was formerly only "For authors" - now I've broken down guidance into 4 different pages for different personas:
- Skill authors
- Skill installers and users
- Skill distributors (people designing plugins, directories, marketplaces)
- Coding agent harness implementers

Notable new details include:

Copilot CLI is the first coding agent I've observed enumerating every file path when you activate the skill, which means every non-skill file inside your skill bundles, like evals/ or READMEs, license files, benchmark or signing files, or other non-skill info, carries a token cost in file path enumeration for every skill activation
Like Claude Code, Copilot CLI strips YAML frontmatter from skill content, so models never see compatibility or version fields or other details that you want to convey
A description field that is over the length, which Copilot CLI counts in UTF-16 code units (a new unit I haven't observed yet in other harnesses), gets the skill rejected from the catalog entirely, making this the strictest description enforcement I've observed
Copilot CLI rejects non-ASCII skill names before any counting, which the reference validator does not, so the reference validator may pass skill names that Copilot CLI won't load in its catalog

For the full details, check out the updates on the Agent Skill Implementation website or GitHub. It has been an illuminating addition! It's making me want to add even more coding agent harnesses to the benchmark, because I'm seeing so many ways things have diverged that break cross-platform portability...

Week 10 at New Job, and here's what I'm thinking about

Fri, 25 Sep 2026 09:12:30 -0400

Week 10 at New Job, and here's what I'm thinking about: how does the vocabulary you use in your product affect agent outcomes?

We have some products where the terminology we use does not quite align with the terms that other products in the industry use. In some cases, we use the same term to mean something related but slightly different, while in other cases, we use a different term than the industry uses. This is independent of something else we do occasionally, which is use a term to mean different things in different documentation pages. 😬

Our PM and DX team has already identified that these terms are likely to be confusing to both humans and agents. But what we haven't been able to say is whether the term usage affects agent outcomes. We've also got three slightly different eval shapes to try to detail the term confusion, asking slightly different questions:

Compare how this term as we use it relates to how specific other named software in the industry uses it; identify the conflicts
Given the term, how would an LLM define it without our product knowledge, just from its baseline training data? Separately, given our definition, how would an LLM name it? And what is the delta between our definition and the LLM baseline definition, and is it likely to cause real confusion?
Given a task that relies on the agent understanding our definition, does an agent fail to complete the task or otherwise struggle with it?

I'm really curious if anyone else has been digging into this, and if so, are there other vocab/terminology eval shapes you're using? And how often have you found the terminology actually shifts outcomes, versus being more "cosmetic"?

So far, I haven't yet been able to find an eval case where the terminology confusion actually affects agent outcomes in practice. I don't know if I just haven't found the eval case where this matters, or if agents are more adaptable to term confusion than we think.

In case you didn’t know already, Fern is awesome

Wed, 23 Sep 2026 13:18:07 -0400

In case you didn’t know already, Fern is awesome. They just added something new to make it easier to test their Ask AI functionality because I asked them to 💖 👏

For some upcoming work, I wanted to run a small eval project to see what information users would get in response to questions using the Ask AI widget in our Fern-hosted docs. They expose a Post Chat Completion endpoint that gives you programmatic access to the tool, but I noticed two things:

The widget scopes retrieval to pages under a product path, but the endpoint didn’t expose the ability to scope the retrieval similarly
When I was hitting the endpoint, my queries were showing up alongside user data in the tool analytics, potentially skewing the “real” user queries. There was no way to say “I’m just testing, don’t count this in analytics”

I raised both to @Ryan-Amirthan and now Fern has shipped 2 new params to help!

Big thank you to all involved.

Related, if you’ve got docs on Fern, did you know you can programmatically test and run evals to see if your users are getting the answers you expect? It’s a great way to learn about gaps or conflicting info in your docs. (It does get billed toward your usage, though, so use it strategically.)

Another busy weekend for my open-source projects!

Mon, 21 Sep 2026 08:14:42 -0400

Another busy weekend for my open-source projects! Lots of releases:

skill-validator: the term "characters" in the Agent Skills spec is ambiguous. I chose UTF-8, but someone from China pointed out runes would be more correct, as UTF-8 was cutting off the description early. So I did a little poll to see how the different harnesses implemented description length, and it turns out there are at least 4 different choices of character type already implemented in the ecosystem, and probably more I couldn't see 😬
agent-skill-implementation: I added a couple of new fixtures and checks so we can keep an eye on what type of "characters" the different harnesses support.
agentsummons: updated for current harness versions
agentminutes: updated for current harness versions, added a new record type I observed for the first time in Claude Code related to session cost
skillxp: updated for current harness versions, agentsummons and agentminutes, added drift probing similar to the other libs/CLIs
agent-traffic-classifier: revisited the current state of agent traffic, including adding a lot of new harnesses, updating some of my heuristics for existing harnesses that no longer behave in the same way, and saw two new large-scale crawlers that don't want to identify themselves...

I also wrote a couple of articles (that still need to get approved through a publishing process at work).

Lots going on in agent land when I skip my weekend chores 😅

I have mentioned before that I maintain a research pipeline to help me stay on…

Fri, 18 Sep 2026 13:09:14 -0400

I have mentioned before that I maintain a research pipeline to help me stay on top of AI-related research.

Sometimes that produces gems like this one in my daily report: “Theme ‘Emergent Unsanctioned Autonomy in Frontier Agent Evaluations’ transitioned from emerging to active” 🥲🫠

In case I missed it in recent news, the narrative summary of research activity names the OpenAI compaction summary jailbreak incident. (I didn’t miss it.) I enjoy that the summary included it alongside new research related to over claiming, agents inconsistently completing tasks, and misreporting when they do. 😂

If you wondered why I maintain a pragmatic view of what the tools are capable of, it’s because I have a daily view of what the industry is doing - both good and bad.

Week 9 at New Job, and here's what I'm thinking about

Fri, 18 Sep 2026 08:59:49 -0400

Week 9 at New Job, and here's what I'm thinking about:

Content determines how agents understand and refer to your products. But not all content is equivalent, or even under your control.

With a docs background, I've focused a lot in 2026 about how documentation shapes agent understanding of your product surfaces. (Including both web docs and Agent Skills.) But documentation isn't the only source of content about your products.

On first-party surfaces, you may have any of:

Case studies, testimonials, etc.
Product, industry, and vertical pages that describe how your product solves for specific needs
Blog posts or other technical marketing content
Documentation

But these surfaces are often written by different teams, who have different goals, which can affect agent understanding in various ways:

Many of these pages are written through a different lens that may shape how agents see your product surfaces
When content conflicts across these surfaces, agents may pick one representation of your product which may not be the canonical one, or may conflate information
When there is a large volume of content that represents your product in a particular way, agents may "assume" that's the only, or at least primary, representation of your product, making other use cases less prominent or difficult for agents to discover
These different surfaces often have different maintenance expectations, may contain version-specific information that doesn't disclose a version, or may be AI-generated and contain factual errors

If you're only paying attention to one surface - for example, docs - you're missing all of these other agent-facing representations of your product. And if that content represents your product differently, you have no way of knowing which representation of your product an agent will repeat to a human user or rely on during implementation.

This is a great example of a high-impact force multiplier when it comes to…

Thu, 17 Sep 2026 15:20:00 -0400

This is a great example of a high-impact force multiplier when it comes to using AI for docs.

It’s also near-and-dear to my agent experience philosophy; agents churn and cannot recover when error information is lacking. I think better error information is one of the most universal agent experience improvements a product can make; all agents will hit errors from time to time, and making those errors recoverable is AX in action.

I’ll even go on record as saying that spending time remediating/improving error information is more important than spending time on Agent Skills. Not all customers will use your skills, but all customers will hit errors.

Time for a crossover episode!

Tue, 15 Sep 2026 07:57:05 -0400

Time for a crossover episode! 😁

Some of the updates to the Agent-Friendly Documentation Spec over the weekend came from @RohitDocs, who helpfully raised some observations about RAG systems and what ingesting for those systems needs. I incorporated some of his suggestions, but some of it was best solved by - wait for it - metadata!

Well, I happen to know someone who is working on metadata right now; @hawkeyexl has proposed some metadata vocabularies that seemed to have a high degree of overlap with some of what Rohit’s RAG observations needed.

I now have an open question that Manny is considering: https://github.com/hawkeyexl/manni/issues/36

This kind of collaboration is how we get to something that’s truly useful for the community. Lots of us have niches where we’re working on something specific, but connecting across these efforts is how we build something useful for more than just us.

Big thank-you to Rohit and Manny for the collab!

The Agent-Friendly Documentation Spec got a version bump over the weekend…

Mon, 14 Sep 2026 08:37:58 -0400

The Agent-Friendly Documentation Spec got a version bump over the weekend, bringing it to 28 checks (5 new) at v0.6 😅

The new checks include:

bot-protection-interference: bot-protection systems can interfere with coding agent documentation fetching, so this check identifies three different forms of bot protection that can block coding agents from viewing your docs
page-size-transfer: the spec already had page-size-html but that was a post-conversion metric; the new check is about how much of the content is serialized framework payloads, which is another form of "request is too large so coding agents can't see your content"
single-fetch-completeness: looks for pagination in markdown responses, and verifies the continuation is machine-followable
markdown-link-portability: links served in markdown should be absolute, not relative, and should resolve to the representation they promise - not a soft-404
embedded-data-serialization: machine-generated static representations of dynamic content can push otherwise prose-light pages beyond coding agent truncation limits, so this check is about the size of those bulk elements

I've also added two new interaction effects:

Bot Protection Degrading Scan Reliability: bot protection enforcement can engage mid-scan, so this interaction effect is about identifying what bots can see and measuring it before bot protection engages
Dynamic Content Rendered Statically: this involves three of the new checks, plus markdown-content-parity and the Category 3 size checks, and is about the different ways that flattening dynamic content for agents can fail

Notably, these additions also pushed the Agent-Friendly Documentation Spec website beyond the truncation limit for agent fetches, so I've now broken the website down into separate pages so agents can consume it. Since this breaks the old URL path, I've also moved it to a web URL, officially recognizing that this is the "Web Documentation Delivery Spec" - and committing to at least two more companion specifications I've been dancing around for months:

Content composition: what documentation should contain to serve agents well: factual consistency across pages, structure and density suited to machine consumption
Repository-local documentation: docs serving coding agents that work inside a repository, where discovery happens through grep and file listings rather than HTTP

If you have any thoughts about what needs to go in the new content composition or repository-local documentation specs, please file issues on the GitHub repo at agent-ecosystem/agent-docs-spec - I am happy to discuss!

The afdocs CLI is not yet updated to reflect spec v0.6; I'm hoping to get those changes into the CLI/lib in the next week or two.

Week 8 at New Job, and here’s what I’m thinking about

Fri, 11 Sep 2026 08:58:54 -0400

Week 8 at New Job, and here’s what I’m thinking about: how do you help agents understand changes to product positioning?

We’ve got products that have had substantial development in the last 6 months, but agents remain stuck at a moment in time before that development. They give users wrong information about capabilities, or understand our product incorrectly.

We’ve got some products that are intentionally changing positioning to better align with org strategy and lessons learned from other products. How do we help agents understand shifts to intended personas and use cases? How long does it take, for example, for updated docs to feed into AI model training crawlers and answer engines, and become reflected in coding agent sessions?

What do you do when some sources of information are under your control and can be updated, but other sources of information from media or third-parties aren’t under your control and reflect outdated positioning? And how does that affect agent understanding of product positioning?

I’m starting to think about how to design one or more studies to better understand this. If you have thoughts or are doing anything around this, I’m all ears!

I really want to do really cool, novel, exploratory agent experience studies…

Thu, 10 Sep 2026 18:53:34 -0400

I really want to do really cool, novel, exploratory agent experience studies and experiments. And I have faith that I’ll get there eventually.

But so far, I just keep finding myself pulled back into docs-related things.

So, PSA: before you can do all the cool stuff, you need good, up-to-date docs that agents can access. Docs are the foundations that AI model training crawlers and answer engines use to learn about your products. Coding agents refer to them in user tasks. If agents can’t access the info, or if it’s outdated or contains contradictions, you’ll have problems and nothing novel can save you.

There is a slightly weird thing about working at an AI company when you

Tue, 08 Sep 2026 08:58:27 -0400

There is a slightly weird thing about working at an AI company when you... take a pragmatic view of what the tools are capable of.

There was an exchange last week that has stuck in my head, which sorta encapsulates the whole thing.

Me: "And even when an agent can write the code, and it compiles, it is often less performant than our libraries." (Speaking of our kernel libraries.) Them: "Then tell them to make the code more performant. I've gotta believe it's capable of writing code better than a human. Otherwise, what are we doing here?" Me: "I haven't seen evidence of that."

Shortly after that, the person left the room. I don't know if it was because of this exchange, or they just had somewhere else to be.

But here's the thing. Yes, AI is great. Yes, it continues to improve. Yes, I use it all the time.

But I believe that currently, someone with domain expertise can often still write better code (or prose, or docs) than AI. Maybe not faster, but more correct, or more performant, or more aware of edge cases, or better fit for an overall system or pipeline, or any of the many things humans can still outperform AI in.

It's a great democratizer. It lets people who lack domain expertise create things they wouldn't be able to create otherwise (myself included). But I keep being confronted with cases where AI output is less than human.

Which I guess means I will keep having encounters like this with my peers.

Week 7 at New Job and this was an onsite for my team and some of the teams we…

Fri, 04 Sep 2026 08:32:55 -0400

Week 7 at New Job and this was an onsite for my team and some of the teams we work with closely.

While I love my remote life, it was great to meet people in person, see the pretty epic office, and collab on some chonky problems.

When you’re part of a team that works cross-functionally, it’s really hard to beat face time with partner teams.

We had some really interesting discussions around who is a developer now, whether developers and agents are independent users with their own journeys, and how we can better understand the impact of changes we may be making to serve one agent audience (AEO, model training crawlers) on other agent audiences (coding agents).

Also, metadata.

Great week!

Week 6 at New Job, and here’s what I’m thinking about in agent experience land

Fri, 28 Aug 2026 08:46:25 -0400

Week 6 at New Job, and here’s what I’m thinking about in agent experience land:

Enabling agents to discover the right information at the right time is still a huge unsolved problem. Skills are an attempt to do that, but they have their own problems, from harness/model combinations just NOT choosing to invoke them to authors writing them at the wrong level of abstraction or filling them with unneeded/unhelpful information.

Progressive disclosure is the principle at play, with the recent “The New MCP Roadmap” announcing a progressive discovery effort for MCP tools, a problem I’ve seen firsthand with enterprise customers. Skills also attempt to provide progressive disclosure. It’s the right principle IF you can get agents to decide they need more information and actually request it.

A problem I’ve continued to see across all “agents must request more information to successfully complete a task” - whether that be load a tool, visit a docs page, or use a skill - is that plenty of times, the agent just chooses not to request more information. It proceeds with what it has, guesses, and fails, and has to spend time/tokens recovering or just fails to recover.

I’ve also been thinking about Opus, specifically; I think some of its “more expensive, slower, over-engineering” tendencies may be related to trying to solve this. I.e. I think Opus is trying to get the information it needs to complete the task successfully, but it’s manifesting as these behaviors.

So, hard problem remains hard.

Not gonna lie, I didn’t make a lot of headway with my local inference…

Wed, 26 Aug 2026 08:40:44 -0400

Not gonna lie, I didn’t make a lot of headway with my local inference experiments with my beefy gaming PC. A beefy gaming PC with one GPU, even the best one I could buy, is not an inference workstation.

The models I could run ran lightning fast, but they were no match for the frontiers in coding and that’s most of what I use AI for.

Really curious (and tempted) to go down this rabbit hole with the new Apple hardware. Wanna see some data from people actually using it.

FYI, one run is not enough to “prove” agents can or can’t do something

Tue, 25 Aug 2026 08:42:06 -0400

FYI, one run is not enough to “prove” agents can or can’t do something.

Two isn’t, either.

Not even three.

It takes a lot of runs to produce a meaningful finding.

For anyone who uses agent-ecosystem tools, I've had a busy weekend for…

Mon, 24 Aug 2026 08:02:41 -0400

For anyone who uses agent-ecosystem tools, I've had a busy weekend for maintenance and everything has gotten updates:

afdocs: couple of small bug fixes and --canonical-origin now accepts a prefix path to support previews shipping from a different base
skill-validator: couple of small bug fixes in YAML parsing and llm-judge instructions
agentsummons: updated for current Antigravity, Claude Code, and Codex harness versions
agentminutes: updated for current Antigravity, Claude Code, and Codex harness versions + added prompt token normalization (to some degree, the accounting is weird) across Claude Code + Codex. Notably, Codex's log format changed again so there are some changes to how you would promote certain event types.
skillxp: updated agentsummons and agentminutes dependencies for current harness versions

Thanks to everyone who PR'd and filed issues on the tools. Really happy folks are finding them useful.

Interesting research paper dropped on the 20th about how coding agents…

Sun, 23 Aug 2026 12:11:05 -0400

Interesting research paper dropped on the 20th about how coding agents discover, read, and write technical documentation: https://arxiv.org/pdf/2608.20195

The main finding is that agent instruction and plan files are the primary agent documentation interaction interface, with agents rarely consulting classical genres that documentation teams focus on (10.6%) and far more rarely consulting API documentation (1.3%)

BUT there are some problems with the methodology and data set. They've scoped specifically to "repository-local, file-based documentation interactions." It doesn't observe docs read through a browser, and explicit documentation-retrieval tool calls were almost entirely missing from their data set (only 16 events).

Also, the data source skews heavily toward one usage pattern. It's 83.8% Claude Code sessions, and Codex has pretty different reading characteristics. It is also entirely composed of developers who opted into one service's checkpoint logging feature on public repositories, with short routine sessions over-represented and most failed sessions never captured. This dataset self-selects into a specific usage pattern or behavior that isn't representative. They also encountered firsthand the issues that prompted me to write agentminutes to normalize session logs from different harnesses into comparable event types.

People who only read the opening numbers may conclude "agents don't use API docs" (based on the 1.3% number) but really, what they've shown is that "when working inside a repo, agents rarely read local API reference files."

There's a lot of missing context in the methodology and data set of most research papers, and it's important to dig in so you can understand what the findings really show.

Week 5 at new job, and here’s what I’m thinking about

Fri, 21 Aug 2026 07:59:32 -0400

Week 5 at new job, and here’s what I’m thinking about: what does MVP look like for a team that is new to performing product evals?

Is it - a set of eval cases covering install, a handful of use cases, and one or two recover paths? Should it include “discover” and “evaluate” tasks; I.e. how much is a human deferring selection of technology/solution today, really? Do we introduce the idea of conditions or specific task completion paths; I.e. “install using pip” vs. “install from GitHub/local build” - or leave it open-ended?

And does it need to include considerations beyond user task? I was chatting with @rhyannonjoy and they brought up safety considerations. Does an MVP product eval case set need to map the idea of “safe” and “unsafe” agent actions and include evals that consider that? How much is agent safety a product consideration, versus being a harness or policy consideration?

My gut says this is all valuable, but some of it is beyond MVP for teams who are new to performing evals… but if something beyond MVP is needed, who sets up and maintains that, and when?

And of course, what does it look like to operationalize all this? And what rough edges do we need to smooth over so teams don’t have to become an expert in EVERYTHING? 🤔

Another random “agents are using your stuff in weird ways” observation

Thu, 20 Aug 2026 10:56:00 -0400

Another random “agents are using your stuff in weird ways” observation: I’m running some evals, and in one run, Codex visited a single documentation page 7 times with different queries to find the information it was looking for.

Saying it again for the folks in the back: agents don’t “read” like humans do.

At the end of Week 4 of New Job, here's what I'm thinking about

Fri, 14 Aug 2026 07:49:56 -0400

At the end of Week 4 of New Job, here's what I'm thinking about: agents don’t use your product like humans do, OR how you expect them to.

It’s the age old “you design a product to do X, user does Y, Z” - but for fun, agents also do “L, and something that looks like N-dimensional Foo.” It’s wild watching what agents decide to do.

For example, I’m working with a team that expected an agent to use a library by either:

Running a provided Python file
Running a provided tool

Instead, agents mostly:

Wrote and executed their own Python files
Wrote Python in a shell script

If you’re evaluating a trajectory to decide what “good” looks like, it would be easy to look only for the former and entirely miss the latter. And if you supply build scripts and tools, agents may never actually use them.

In another example, I was exploring how different interventions could improve agent accuracy and performance. I wanted to test each of these conditions in isolation, and then check some together to see what the agent would reach for when multiple options were available:

Baseline (isolated, no augmentation available)
Existing documentation
Modified documentation
A custom CLI
A JSON file with machine-readable content

I disabled harness web fetch tools for the baseline test; one harness mostly failed, but another suspiciously got the task right every time. On inspection, it was working around the disabled web fetch tool by importing Python’s urllib and fetching documentation that way. So I thought I had designed a no-docs test, and it mostly worked for one harness, but a different agent worked around it.

If you’re designing agent experiences without testing how agents use your product in practice, you may be designing for a case that never happens. Agents use your product in weirder ways than you’d expect. And when you’re trying to isolate conditions for evals, don’t forget to check for how agents work around your constraints.

Thinking more about my Fable iOS app development project over the weekend; it…

Tue, 11 Aug 2026 08:30:28 -0400

Thinking more about my Fable iOS app development project over the weekend; it was close to frictionless. But there are still things you have to do in the App Store Connect or CloudKit web UIs that agents can’t do. The handoff from “agent wrote the code” to “human has to take steps to deploy it” is now the point where friction is introduced.

That’s the next horizon for “agent experience” and I want that to be solved already.

If your product surface has actions that require a human to log into a web UI and click buttons or configure things, find a way to let agents do it. And then make sure they know how.

Fable built me a new app over the weekend

Mon, 10 Aug 2026 08:33:25 -0400

Fable built me a new app over the weekend. It took a few hours of iteration, mostly because I didn’t know exactly what I wanted well enough to specify it up front.

Aside from some minor CloudKit Sync issues, and some stuff you have to do in Apple Developer UIs, I did nothing except chat and everything just worked on the first try. I did read the code for quality/security stuff and it’s very reasonable.

This is a jump from the last app I wrote with AI. These things continue to get better. Unlike the last time, Fable proactively launched the simulator and inspected the UI through screenshots. It built scripts to generate sample data for UI iteration from real data I had on disk. It read existing CI pipelines to figure out how the data was generated and found a minimal, no-fuss way to fit a step into an existing pipeline to generate a version of the data that this app could use. Even just 6 months ago, I would have had to do so much of this myself.

I’ve spent this year genuinely believing this is the direction that software development is moving, but it’s wild to see it in practice.

(The app is something I won’t publish beyond private TestFlight; it compiles a reading list for me and gives me a native view of some data from a daily report I generate for myself from a series of CI pipelines that run overnight. A new CI step emits as JSON the same data that powers a web dashboard for me. Now I can read my morning briefing from my iPhone or iPad, and read state syncs between both.)

At the end of Week 3 of New Job, here's what I'm thinking about: eval design

Fri, 07 Aug 2026 08:47:24 -0400

At the end of Week 3 of New Job, here's what I'm thinking about: eval design.

Engineers are no strangers to writing tests. So I think a lot of people assume engineers will automatically be able to write good evals. But I think the skills are not exactly the same. There are new things to learn.

So now we have a learning design exercise. How do we help people learn how to write good evals? What tools do they need to kick-start the process? How do we scale this to teams who haven’t already been thinking about evals?

And related, how do we get evals embedded as part of the “definition of done” in the product development cycle? Teams are busier than ever, so asking them to learn a new discipline and then embed it in their day-to-day workflows seems like a big ask. But it also seems like table stakes for any product that wants to be agent-friendly.

So this week’s agent readiness mindset is all about learning design and change management.

Your Agent Skill isn't the same on every platform

Mon, 03 Aug 2026 08:14:07 -0400

Your Agent Skill isn't the same on every platform. The Agent Skills spec is un-versioned and under-specified. Harnesses may have implemented support for skills before official implementation guidance landed, and may not have kept up with spec guidance. And that means that each harness may have its own story of how it supports skills, with no way to communicate to users what that looks like.

I've automated 38 of my 40 checks, with every finding cited to an archived transcript rather than the model's self-report, and I can now tell you that there are observable differences in how Antigravity CLI, Claude Code, and Codex CLI support skills, including:

Antigravity and Codex CLIs use the skill name from the frontmatter in SKILL.md, while Claude Code uses the directory name. If the names don't match, your skill may answer to different names on different platforms, potentially breaking docs references or references in other skills.
Claude Code strips frontmatter entirely. Aside from its name-and-description-only listing, other frontmatter fields such as compatibility notes, metadata, and any custom fields you add never reach the model through any platform channel.
Name collisions contradict the official guide. The implementation guide calls project-over-user precedence "a universal convention". But Claude Code resolves user-over-project, and Codex doesn't resolve it at all (the model picks).

For a full breakdown of how each platform handles skills, including which ones are spec compliant and where they diverge, as well as authoring guidance based on my findings, check out the updated site.

Links from the comments:

I’ve been chatting with a few folks lately about how LLM writing is just… not very good

Sat, 01 Aug 2026 23:29:59 -0400

I’ve been chatting with a few folks lately about how LLM writing is just… not very good. They use a lot of words to say very little. And we’ve all gotten to the point where certain words trigger us because we see them in AI slop everywhere.

But. I also use AI to help speed up my writing process sometimes. I scaffold content with a quick sketch of my ideas and sources to pull from, and let AI help me fill in details.

And then I edit judiciously because of those speech patterns, trigger words, and verbosity.

I finally decided to do something about it and hook up Vale in some of my personal projects, with some rules designed to target AI writing. I’ve pulled some from third party rule sets that folks have published, and made some of my own. I’ve set it up with a pre-commit hook so no new or edited file with rule violations gets committed.

Style guides in markdown, like in skills or rules in AGENTS.md, are just suggestions agents can ignore. Linters that block commits force agents to follow the rules. If you use AI for writing, lint your prose.

https://vale.sh/

At the end of Week 2 of New Job, here's what I'm thinking about: evals

Fri, 31 Jul 2026 09:00:33 -0400

At the end of Week 2 of New Job, here's what I'm thinking about: evals.

A lot of people lean heavily on evals as a tool to assess agent task completion performance. But we don't have a shared idea of what "good" looks like. People are indexing on different assessment criteria, tracking different metrics, relying on different evaluation conditions, or working with custom evaluation frameworks that may not follow design best practices. So Team A's evals may be very different than Team B's evals, and as a person trying to read eval results and take some action, those differences matter - and many of them may be invisible to the person reading a report.

Separately, in terms of thinking of evals as an agentic analog to unit tests, I'm thinking about how we can be sure the evals are running under a representative range of conditions. Just as in a unit test situation, we can't only run a given evaluation under the happy path conditions. We need to be thinking about the range of conditions under which our customers may be using our products; brownfield projects, greenfield projects, with properly-configured tools, with mis-configured tools, with only a subset of tools - and understand how agents perform in each of these conditions. A single task with a single environment configuration and no conditions isn't a representative picture of how agents perform.

And finally, I'm thinking about how we connect evals to the other facets of the DX process. If you do work with user journeys, jobs-to-be-done, personas, and other exercises mapping DX surfaces - how do we connect evals to those mappings to make sure the DX surface is well covered? Agent experience needs to work within agent capabilities and harness constraints, but it isn't completely independent from the rest of your DX life cycle, and those connections should be considered in eval design.

Random observation: FastAPI has become the default vibe-coded server

Thu, 30 Jul 2026 11:47:46 -0400

Random observation: FastAPI has become the default vibe-coded server. My agents basically always reach for Python/FastAPI when spinning something up that needs a server unless I specify something else, and now that I’ve seen it in a handful of my own projects, I am basically seeing it everywhere.

I would love to dig into why agents reach for this first. I’ll bet there’s a lot we could learn about agentic product selection. I’m really curious how much it is just - this is well-represented in GitHub data/public repos that a lot of agentic coding knowledge is probably based on. Or whether FastAPI inherently has any characteristics that make agents find it “easier” to use and reach for it as a default. 🤔

Consider this your friendly neighborhood reminder that Agent Skills need…

Wed, 29 Jul 2026 08:30:13 -0400

Consider this your friendly neighborhood reminder that Agent Skills need regular testing and maintenance to stay useful, or should be retired when they have outlived their useful life.

If you’ve written a skill earlier this year, it may already be silently degrading. New models, changes to harnesses, and changes to your own process and project can all cause skill performance to change.

Sometimes, models become capable of doing the thing on their own and your skill causes unnecessary thrashing. Sometimes, changes to harness instructions or tools can cause your skill to perform differently, and it may no longer deliver the results you expect. And if your skill covers a product surface or project that is in active development, there may be changes that render your skill outdated.

You need a regular process to re-check skill performance. The industry is moving fast. If you’re going to create these artifacts, you need to commit to maintaining them as things change around you.

Ok, at the end of Week 1 of New Job, here's what I'm thinking about

Fri, 24 Jul 2026 09:01:59 -0400

Ok, at the end of Week 1 of New Job, here's what I'm thinking about:

Agents and humans do not need the same things. In fact, humans and humans don't need the same things. If you've ever been part of a persona-mapping exercise, drilled into audience segments, or tailored your content and pitches for different human audiences - you know what I mean.

Agents are the same. When I say "agent," I am referring to a combination of harness + LLM. Agent behavior is LLM inference mediated through harness tools and capabilities.

If you've ever tried using Claude Code and Cursor for similar tasks, and noticed different behaviors and outcomes, this is why.

So agent experience must understand the behavioral capabilities of different agents, what agents your customers are using, and how those behavioral differences interact with your product surfaces.

This is wide open space for most businesses today, so lots of opportunities but I also expect to see a lot of diverging practices as people try out what works.

New tools, who dis?

Sun, 19 Jul 2026 23:39:09 -0400

New tools, who dis?

I keep messing with cross-harness experiments, and running into the same problems over and over:

My agent re-discovers the valid headless invocation flags in every session, and runs into behavioral quirks that only turn up in use
I haven't found an observability tool that works with the harnesses I want to observe, doesn't mess with the sessions, and is accessible to me as an individual
If I want to read and compare session logs to evaluate experiment results, they produce different shapes that have to be normalized for valid comparison

I can't decide if it's a fool's errand given how quickly these things change, but I've spun up two tools to help:

agentsummons: CLI to help manage invoking agent sessions for experiments
agentminutes: CLI to parse native agent harness session logs into one unified, comparable event schema

Built in Go, because I love Go, but I've added npm and PyPI wrappers, so you can use them from your preferred ecosystems.

Very early releases (v0.2.2 and v0.2.0 respectively) and I have no idea if it'll be feasible to keep up with the churn on harness tools, but I want them and figured other people might find them helpful, so 🤞

Currently supports Antigravity, Claude Code, and Codex, because that's what I'm experimenting with at the moment, but if you want to use these and need support for another harness, I'm open to issues/PRs.

The links are in the comments.

Links from the comments:

I wish Anthropic hadn’t added “memory” functionality to Claude Code

Tue, 14 Jul 2026 15:12:42 -0400

I wish Anthropic hadn’t added “memory” functionality to Claude Code. I almost never want it, for a variety of reasons:

It doesn’t have good judgement about what should become a memory
I already have project documents whose contents I curate (AGENTS.md, CLAUDE.md, skills/hooks etc.)
I don’t want to pollute context with content that isn’t needed in every session

I generally don’t want to waste the input tokens on Claude Code reading whatever it has decided is memory, and waste generation tokens on writing it. Especially when the harness seems to “forget” memories anyway when performing tasks in-session.

Blarg.

Well, the news is out, so I guess it's my turn to share here

Fri, 10 Jul 2026 21:58:34 -0400

Well, the news is out, so I guess it's my turn to share here: after 5.5 years at MongoDB, I'm moving on for a new adventure.

I remain grateful that @cbush took a chance on someone who did not have coding skills to join the Developer Education, Realm team way back when. I was the first technical writer without dev chops to join this team, and I spun up on Swift/iOS/macOS development while learning about mobile application databases and everything it takes to ship apps. I still think that was a great product and remain bummed that the company deprecated it. I went from no dev chops to cutting my teeth on C++ under Chris's mentorship, and I'm still proud of growing those skills.

When the company deprecated Realm, Kyle led our team through redefining ourselves not once but twice. Under Kyle's leadership, and with the support of our Director of Documentation Jonathan, we got the opportunity to drive accuracy and developer experience initiatives across the docs org. Our stage got bigger, and I learned so much about moving from the weeds to strategic messaging for non-technical stakeholders. To Eliza and Melissa, thank you for helping me learn how to hone my messaging!

To my teammates Cory and Caleb - I have loved building alongside you these last few years. Leaving you and Kyle is the hardest part of moving on. 💖

To the many more folks I've worked with or crossed paths with over my years at MongoDB, you've all helped shape my time there and I will take that impact with me and be rooting you on from the sidelines. Tech is a surprisingly small industry - maybe we'll work together again someday!

I've got a new challenge coming up and had Claude Code design a study plan for me (again)

Fri, 10 Jul 2026 09:01:27 -0400

I've got a new challenge coming up and had Claude Code design a study plan for me (again). Now I've got day-by-day lessons building progressively, a structured note-taking template, curated resources... and it only took ~10 minutes of describing what I had in mind, iterating, and validating the resources.

I know AI isn't perfect and it takes iteration to get good stuff out of it, but wow, is it so useful, and much faster than hunting down stuff myself.

One of my good friends is a Director of Engineering at a software company

Thu, 09 Jul 2026 09:07:02 -0400

One of my good friends is a Director of Engineering at a software company. He was telling me last night about how he was handed some requisitions for roles that he hadn't fully vetted after a recent re-organization.

After being informed about some new project work as a result of the re-org, he looked at the reqs again - and the roles were not aligned with the new work he had just been handed. So he has realized he probably needs to update the roles and post them again. After HR had already posted them, gathered 2,000 resumes for one role alone, and taken them down again.

Are they the right 2,000 resumes? Probably not, in light of new requirements related to the unplanned work he was handed.

All this to say, oof, it seems like a rough time out there folks. If you're in the market and missing out on roles, there is every chance that it's not you at all. And if it looks like companies are doing silly things with posting and re-posting similar roles, it may not be anything malicious - just new requirements surfacing or other communication gaps.

Thousands of motorcyclists have ridden the Pan American Highway to The End of the World

Sat, 27 Jun 2026 13:59:54 -0400

Thousands of motorcyclists have ridden the Pan American Highway to The End of the World. I'm one of them.

In 2010-2011, my partner and I made one of the iconic pilgrimages of the overland motorcycling world, riding from Boston to the bottom of South America. We covered 18,000 miles across 13 countries in what was truly the trip of a lifetime.

I've been thinking about it a lot lately because of one very important thing it taught me: things will happen when they happen.

In the United States, we live a fast-paced life of instant gratification. We get annoyed when we have to wait a few minutes for something.

In most of Central and South America, things come at their own pace. Maybe the shop will open an hour late. Maybe you'll get somewhere during afternoon siesta and it'll be closed. Maybe the border official wants an extra bribe today and you'll have to wait until tomorrow when a different official is working to cross. Maybe plans will fall apart and you'll have to do something completely different.

That trip was a master class in dealing with uncertainty, learning patience, living with discomfort, and rolling with change.

It has been 15 years since that trip; the motorcycle lives in my shed now and I haven't ridden in ages. But those lessons are very much top of mind. I am impatient to move forward and participate in fast-paced spaces, rushing through a period of discomfort and change. But am reminding myself that things come at their own pace.

And there is plenty of beauty to enjoy along the way.

A wild thing about this is that orgs that use products that restrict bot access…

Fri, 26 Jun 2026 08:21:09 -0400

A wild thing about this is that orgs that use products that restrict bot access to their docs, such as Vercel and Cloudflare products tailored to this, are also blocking agent access to docs. Agents can’t complete challenges.

So in practice, if you block agent access to your docs, you’re blocking an agent’s capabilities of looking up your product’s details in real user task flows to help users complete tasks. So agents will look for other sources, make stuff up, or choose other products where they can actually get relevant details.

Thursday thought exercise for y'all - how do you handle "best practices" in…

Thu, 25 Jun 2026 09:09:42 -0400

Thursday thought exercise for y'all - how do you handle "best practices" in docs, and how would you convert those to config for coding agents?

In my experience, requests for best practices docs tend to be "distill 30k pages worth of content into a one-pager" - which doesn't actually work. So we tend to pick some particular persona or job-to-be-done and provide best practices for that, which just restates content that is scattered across more detailed task-oriented or feature-oriented docs pages.

Orgs are now starting to look at "what Cursor Rules or Claude Hooks can I distribute for my product" - which looks an awful lot like "best practices" distilled into config. So my first question becomes - what persona or job-to-be-done are we trying to support through this config? One stack's rules/hooks may look very different from another stack's - or if you're looking at it from a persona perspective, a database administrator's rules/hooks are likely to be very different from a developer building a CRUD-based web app.

Has anyone seen any examples of orgs/products that are doing this well yet? Have you started having these convos in your org? How are y'all thinking around these things?

I don’t live in a major metro area - on purpose

Tue, 23 Jun 2026 14:03:43 -0400

I don’t live in a major metro area - on purpose. I left a major metro area almost a decade ago to live somewhere surrounded by trees, with a small pond, and lots of space to futz around outdoors when I’m not touching computers. Sometimes I even take meetings from my back deck - it’s great.

A big storm blew one of our trees down last week. I was able to use my tractor and a maasdam come along to stand it up again. Time will tell if it survives.

I can’t tell you what it does for my quality of life to live somewhere like this. I derive a ridiculous amount of joy from futzing around with my tractor, or walking the dogs around before or after work, or just being able to step outside and hear birds chirping, or the neighbor’s chickens, or one of my neighbors doing something with a tractor or a chainsaw or whatever equipment they happen to be running that day.

I know with RTO a lot of orgs expect employees to be in-person or hybrid. I have no interest in relocating and giving all this up. As a remote worker who lives somewhere like this, I am still perfectly capable of doing industry-leading work around agents and AI. In fact, part of why I am able to maintain such a high level of productivity over time is that I live somewhere like this with so much to recharge my battery at my doorstep.

Whomp whomp, weekend poking of local AI was not a home run

Mon, 08 Jun 2026 08:36:52 -0400

Whomp whomp, weekend poking of local AI was not a home run. I'm not quite ready to give up, but I'm a lot less optimistic than I was about getting something useful out of the process. I'll write up the details when I get a chance, but some takeaways...

The good:

Pi is an awesome harness if you want to customize. The analogy to a bare-bones IDE that you can built out to whatever your heart desires absolutely holds here; it's like an agent VIM or Emacs that you can turn into whatever you want.
I have apparently used enough harnesses at this point that I have Opinions about what I like/dislike/what behaviors I want. So being able to write my own tool implementations or extensions to guide behavior is super cool and could become very addictive.
Running right-sized models on my Windows GPU is BLAZING FAST. I have never seen an agent work this fast; it streams and makes tool calls much faster than I can read. It really makes me want to dig into why it's so fast compared to the big-provider APIs I'm usually working with; presumably it's the lack of reasoning, but I want to learn more.

The bad:

Pi has basically no batteries included. So you have to customize just to get to basic functionality, like a permissions system or web retrieval functionality. It'll probably make sense to have starter distros that come with what it takes to get a functional agent.
Getting local models to run is... a wild time-consuming rabbit hole. I spent 7 hours in lib conflict/bug resolution hell to get Qwen3-Coder running locally; 3.5 hours just getting things to compile, and longer to get it running past the profiling stage and serving on my local network. And then I installed a completely different stack to use Devstral. It is not for the faint of heart and would have taken me SO LONG (days) without Claude Code.
Even with every optimization I could throw at it, the local models are just not up to even basic tasks. Qwen3-Coder offers better code gen, at the cost of being unreliable at driving the harness. Its tool call format doesn't play nicely, and it's not as good at instruction following and tool calling in general as other models. Devstral drove the harness like a pro, using all the tools quickly and consistently, but then crapped out when I tried to get it to generate docs updates. It was a basic generation task and it just kept stalling. I'll try again but am not terribly optimistic.

My big takeaway is that while the local stack is fun to play with, and I love the idea of Pi, I'm absolutely spoiled in my expectations of what agents should be capable of based on using frontier models all the time through paid subscriptions or at work. The local agents I can run on my hardware are where the frontier was a year or two ago. I'm on a beefy gaming system; if I wanted to step up to something that could run more capable models, I'd be looking at $25k to build a completely different system. Not quite where I was hoping to be at the end of the weekend.

Weekend project: I’m finally digging into Pi

Sat, 06 Jun 2026 09:02:32 -0400

Weekend project: I’m finally digging into Pi. Trying to see how much of a difference it makes to have an agent harness that works the way I want it to.

Also experimenting with local models since I have a fancy gaming PC now with a chonky GPU that sits around unused most of the time.

I’m not going to get frontier performance with this setup. But wondering how close to “good enough” I can get in a system that gives me full privacy/full control over how things work.

Technical writing is where implementation validates design

Tue, 02 Jun 2026 08:10:06 -0400

Technical writing is where implementation validates design. AI can’t do it.

Let me tell you a tale of my latest project at work…

A teammate and I are building an Agent Skill Dashboard. It’s a state management tool that aggregates information from many different sources to provide a single record of truth about the state of any given official skill, and to manage processes around idea submission, update requests, and to provide a triage team a tailored view of requests.

I wrote a design document to capture how the process should work. I sketched out details about the end-to-end process, what each actor should see and the actions they should be able to take, and how systems would talk to each other.

Then we implemented it. Discussions happened. We made decisions that diverged from the design.

After building it, I had AI draft process docs for users to use the system. It looked at both the codebase and the design document. It wrote docs that look reasonable at a high level, but every single one has outdated information that doesn’t correctly track either source. Sometimes it pulls in info from the design that didn’t get implemented. Sometimes it pulls in information from implementation but misinterprets what it found. It’s not consistently skewed in either direction, so it can’t easily be corrected with a second pass.

It also records information without understanding what a human needs to know, and why. It documents internal design rationale that isn’t relevant for users following the process. It created a helpful glossary of terms on one page that span all 6 pages, and a user who only views page 5 will never see it. It repeats UI details verbatim, which isn’t helpful - a user can get those details from the UI - and omits the things a user needs to know about where to find or how to create relevant values.

Every technical writer knows these gaps well. It’s exactly this reconciliation that forms the bulk of our work. Figuring out what decisions were made, and why, and what matters for users, when those decisions were never written down - this is the “detective mode” we live in. And no AI system or context augmentation platform or memory harness can capture these details because they either live in someone’s head, or were decided in conversations that nobody wrote down.

So I will spend a few days this week fixing up the AI documentation draft.

And orgs that don’t have people capable of doing this work are going to learn the hard way what happens when they’re missing this expertise.

Leveraging agents for learning this weekend

Sun, 17 May 2026 07:45:03 -0400

Leveraging agents for learning this weekend.

I have realized that my writing-code-by-hand skills are getting rusty because I’ve been working with agents so heavily for ~8 months. So I’ve had Claude Code spin up some exercises for me just to refresh.

As expected, I retain the shape of the algorithms, but the syntax and language-specific reflexes have fallen out of my brain. So Claude broke it down further for me into drills so I can rebuild those reflexes.

Kind of alarming to see how quickly those specifics erode. But unbelievable luxury to have a tool that can create custom drills and exercises for me to practice to regain lost ground.

Also underscores where the value is. It takes me 10-20 minutes to work through a drill, or ~45 minutes for an exercise. But Claude can write equivalent code in ~2-5 minutes. We live in wild times.

Ok, LinkedIn network, help me crowdsource from your lovely smart brains!

Tue, 12 May 2026 09:11:48 -0400

Ok, LinkedIn network, help me crowdsource from your lovely smart brains!

I know I've been posting a lot lately about agent-friendly docs and agent skills, but in the back of my mind, I've been percolating on what "Agent Experience" might look like as a dedicated role/persona within an org. I envision this as the bigger-picture ownership of how agents interact with our software products.

Something really stuck with me from the article @talagluck posted about his Pizza API experiment: how the agents recover from failures. In his experiment, he observed that both Claude Code and Cursor fetched documentation once, failed to successfully write the API calls, but then didn't attempt to fetch docs again - they tried other recovery paths. Only Codex read the docs and explored thoroughly enough to successfully write the API calls without error. (I'll link to the article in the comments - so much interesting stuff there!)

BUT I have been thinking a lot about recovery paths. We know error messages are critical for developers, but we do a poor job with them anyway. That has been one of the most consistent sources of feedback I've seen over my documentation career - not enough details from/about errors and recommended handling/recovery paths. I can see this compounding quickly for agents, and can predict some of the consequences.

What I want from you: does anyone here know of any studies or best practices around agent failure recovery strategies? Any data behind what agents typically attempt to recover from failures, how successful they are, how much token spend it involves, what other mitigations agents reach for if they can't recover? I'm now thinking this would probably be a high impact area of improvement for Agent Experience, but would love to know what prior art may exist around this space, if any.

Links from the comments:

https://www.stateofdocs.com/research/do-ai-coding-agents-actually-read-your-docs

I’m very excited to share that the work that @rhyannonjoy has been doing to…

Mon, 11 May 2026 10:15:59 -0400

I’m very excited to share that the work that @rhyannonjoy has been doing to study web retrieval across agent platforms has made it back to the Agent-Friendly Documentation Spec in the form of a new Platforms page! 🎉

Rhyannon breaks down for us three distinct axes of the web retrieval pipeline across platforms:

Retrieval
Truncation
Summarization

The picture is a lot more complicated than I realized when I started my research with Claude Code a few months ago. Expect bigger updates to the spec soon as we grapple with how to integrate the cross-platform findings into something docs teams can take action on.

Because I didn't have enough agent-related surface area to explore, I'm now…

Thu, 07 May 2026 00:02:11 -0400

Because I didn't have enough agent-related surface area to explore, I'm now speccing out a possible Go query engine inspired by Rust's trustfall.

It's because of agents, sorta - I've been planning a v2 rewrite of skill-validator with a pluggable content policy (and many other things). But the Go ecosystem options for this are - not quite what I'm looking for.

My good pal Claude says I should just ship v2 with one of the suboptimal but extant options. No need to write a whole separate library - just make the shape fit what's available.

Maybe my brain just needs something that isn't agent-shaped to work on. Or maybe it's because people keep coming to me with graph-related stuff, and building a graph-based query engine in Go lets me explore that domain so I can make better assessments of the agent-related graph things that keep dropping in my lap.

Who knows if I will actually ship anything, but it's a fun exercise so far.

Now that we’ve shipped our official company Agent Skills MVP, I am working on…

Wed, 06 May 2026 12:18:01 -0400

Now that we’ve shipped our official company Agent Skills MVP, I am working on what it looks like to mature our skill development process. I’m still forming my thoughts around this but curious how much of this resonates with what other orgs are thinking:

Vibe-coded skills pollute an org’s namespace for dubious gains. I’m implementing a gating process that requires prompts & evals across model families to determine whether a skill is needed and can actually solve the problem as presented - BEFORE writing the skill.
A skill author must be able to articulate the need clearly through prompts and what we expect the model to produce or where we expect it to fail, or you get a poorly-scoped skill that doesn’t quite know what problem it’s trying to solve.
For official company-distributed skills, these are part of the product surface area and should be owned as such.
Not everything can or should be solved with a skill. For some things, the fixes are docs improvements, API changes, hooks/rules or other AI artifacts, or larger cross-cutting initiatives. These resources need an owner that understands the product surface area and which lever is the right one.

More broadly, officially company-distributed AI tools and resources in general are an emerging category. It started with companies deciding they need MCP servers, and building them as one-off agent access planes. But now there is an emerging suite of agent resources that warrant a clear company strategy and ownership. Along with study of how agents use your product suite and where the sharp edges are that need product-level improvements, not just resource bandaids.

I’m picturing something like content strategy, but instead of content, the surface is agents and optimizing for all the ways they interact with your products.

I think we’re watching the birth of Agent Experience in real time, as a distinct but complimentary category alongside Developer Experience.

Curious how other folks are seeing things play out in their orgs. Do you have maturing strategies for this stuff? Are you handling everything ad-hoc and just trying to keep up? The challenge here is compounded by the speed of movement in the AI space right now.

In Agent Skills land, questions for folks who are distributing official company…

Tue, 28 Apr 2026 09:22:45 -0400

In Agent Skills land, questions for folks who are distributing official company skills (yes, I may do too many things 😉):

Do you have a submission process before people start drafting skills? If so, what does that look like? I have been finding in practice that a lot of skills are poorly scoped or not grounded in concrete user issues, and those skills are less likely to be helpful/can cause degradation in task performance, so I'm curious if anyone is building checks for this into their process.
How are people planning for maintenance? I'm testing a yaml manifest that lists each skill, the DRI, a review cadence, and last review date, with automation to ping DRIs when it's time to review. But now I'm pondering the idea of review triggers - i.e. product releases, new models, big agent platform changes, etc. and how that should factor into maintenance.
Do you have any SLAs around skills yet, and/or practices around debugging issues reported for specific agent platforms/product configurations, etc.? Who in your org owns this?

Really curious how other folks are handling this. It shares a lot of similarities with other maintenance processes, but combines them in interesting and slightly weird ways. Would love to hear your thoughts!

Is your org planning for the next agent platform shift, or locking itself in…

Mon, 27 Apr 2026 08:49:56 -0400

Is your org planning for the next agent platform shift, or locking itself in with a specific provider?

My org has rolled out Claude Code widely in the last month or so. Before that, we had GitHub Copilot, Cursor, and Augment. I have watched my peers shift their work to build specific tools that are locking us into the Claude Code platform; Skills with Claude-specific frontmatter fields and tool names, Claude hooks, CLAUDE.md everywhere.

For my personal stuff, I have been keeping things tool agnostic because I have switched agent platforms 3 times since I started messing around with these things. Any given platform starts off affordable for experimentation, then realizes it can't keep subsidizing token costs and raises its prices. We've been seeing Claude Code do that in the last few weeks, and I've had other providers do that before. So I'll probably switch my personal stack again soon.

But for the org, the switching cost is a lot higher. Especially as more and more employees build things that are optimized for a specific agent platform. I'm really curious if any orgs are actively monitoring and discouraging vendor lock-in, or if everyone is just going to have to pay the price when the invoice numbers change. It seems like the big players are counting on the lock-in, but I'm curious if any orgs are actively trying to keep their options open or if that's really only feasible on an individual level.

I just shipped v0.5.0 of the Agent-Friendly Documentation Spec and updated the…

Sun, 26 Apr 2026 23:18:50 -0400

I just shipped v0.5.0 of the Agent-Friendly Documentation Spec and updated the AFDocs scoring tool to match. Major thanks to all the community members who participated in discussions, filed issues or PRs on the spec or the tool, and helped shape the improvements and bug fixes!

If you've been tracking your documentation site's agent-friendliness scores, they're going to change. The scoring is more accurate now, and "more accurate" could be an upside or a downside for your site.

In smoke testing across sites at every grade level, I saw:

Every site's content discoverability score dropped. The tool now checks whether your llms.txt directive appears in both HTML and markdown formats separately, instead of lumping them together. Most sites only have it in one format, so that's a new failure where you might have gotten a pass or a warning.
Page size and content start position scores generally improved. The tool now strips scripts and styles before measuring, matching recent updates to how Claude Code processes your pages.
One major enterprise docs site went up a full letter grade (D to C) because they've added real markdown URL support since I last ran the tool against their site. Their llms.txt links changed from .html to .md, and their server now returns actual text/markdown at those URLs. While I haven't spoken directly with anyone there, the timing lines up with the spec's publication and the tool's growth in visibility, so I'd love to think they found the tool helpful and have been making improvements. Wins like this are good news for docs and for developers using agents.

Overall scores moved between -10 and +8 points. Most changed by 5 or fewer. Only 2 of 6 sites changed grade letters, one up and one down.

If you're using afdocs, I’ll throw a link to the migration guide in the comments with details about the scoring changes and what to expect.

Links from the comments:

https://afdocs.dev/migration/v0.17.0

The Agent-Friendly Documentation Spec just got a version bump!

Tue, 21 Apr 2026 22:15:29 -0400

The Agent-Friendly Documentation Spec just got a version bump! 🎉

Spec v0.4.0 reflects a handful of community requests, including:

Renaming the llms-txt-freshness to llms-txt-coverage to more accurately capture intent
Noting that llms-txt-coverage may intentionally diverge from full sitemap parity for docs sets that curate their coverage, and makes allowances for different coverage measurement modes
Updating markdown-content-parity for a similar purpose; some sites intentionally omit info from markdown pages that aren't relevant to agents, such as chrome, buttons, or sign up CTAs

I'm planning to update the afdocs CLI soon to reflect these updates; hopefully over the weekend.

Major thank you to everyone who weighed in, including @devalog, @njb90, @nicoleomeara-astro, @rosieyohannan, @MattyQ, and @chalin. Really grateful for everyone's feedback to help make this a more useful tool for the community! 🎉

In Agent Skill land, I have been synthesizing my 100+ review comments across…

Mon, 20 Apr 2026 13:00:51 -0400

In Agent Skill land, I have been synthesizing my 100+ review comments across our official Agent Skills corpus into review guidance to scale Skill quality reviews across our docs org.

If you wonder what types of things a human should be looking for when reviewing Agent Skills (beyond technical details, which should be reviewed by an SME), you might find this helpful. I look at:

Scope and Skill boundaries
Decision tree walkthrough
Content justification
Instruction precision
Consistency and narrative coherence
Cross-skill ecosystem awareness

The page also includes my guidelines for which things should block merge, request changes, or nice-to-haves. Available in our meta docs for anyone who might find it helpful:

https://www.mongodb.com/docs/meta/tutorials/review-agent-skill/

Cloudflare's @mvvmm has been getting some much-deserved shout-outs from his…

Sun, 19 Apr 2026 14:10:36 -0400

Cloudflare's @mvvmm has been getting some much-deserved shout-outs from his team for his excellent work on their agent docs monitoring stuff, and now I get to give him a shout-out for making some helpful contributions to afdocs! 🎉

I've just cut v0.14.0, which includes a handful of PRs from Vance, including some bug fixes and performance optimizations - and a new --skip-checks flag for better ergonomics if you need to skip only one or two checks that aren't relevant for your docs.

Really appreciate the contributions here, Vance!

Thanks to @philip

Fri, 17 Apr 2026 09:22:28 -0400

Thanks to @philip. - AFDocs now supports testing against preview/staging deployments with different origins 🎉

In v0.13.0, we've added a new --canonical-origin flag that lets you specify a production origin to point to for URL matching in llms.txt and/or sitemap when you're running against a staging build. This looks like:

afdocs check https://preview-xyz.vercel.app/docs --canonical-origin https://example.com/docs

For more details, check out the updated "Run Locally" docs at: https://afdocs.dev/run-locally.html#production-urls-in-local-builds

I really appreciate the PR, and hope this is useful for folks who want to test from staging.

Hey, docs teams (and web users in general) - it's celebration time!

Tue, 14 Apr 2026 19:34:08 -0400

Hey, docs teams (and web users in general) - it's celebration time! Claude Code has shipped an update that fixes the configuration of its HTML to markdown lib and now it can use gigantor docs pages buried under a mountain of CSS more effectively 🎉

In the v2.1.105 release notes, Claude Code has this unassuming bullet item:

- Improved `WebFetch` to strip `<style>` and `<script>` contents from fetched pages so CSS-heavy pages no longer exhaust the content budget before reaching actual text

An engineer who reverse-engineered Claude Code's WebFetch implementation pointed out in January that it uses the Turndown library to convert HTML to markdown. But as I found in an article I posted in February, Claude Code's Turndown implementation was not configured to strip <style> or <script> tags, so web pages with a lot of CSS or JS script content would eat the entire context window before ever reaching any real page content.

With this fix, Claude Code can now successfully "see" content in large HTML pages! I've confirmed this with some known "bad" pages that Claude consistently complains about. Complaints are gone - Claude can now successfully retrieve the content!

This is good news for documentation teams who do not yet serve clean markdown through content negotiation. Now Claude Code stands a much better chance of being able to find your content in HTML. 🎉

I’ve had an idea and am wondering if anybody is doing this in their orgs yet

Tue, 14 Apr 2026 12:28:12 -0400

I’ve had an idea and am wondering if anybody is doing this in their orgs yet: Skills-as-a-service.

Since my org has published our Agent Skills, we’ve been getting customer requests for very specific things. They wouldn’t generalize well to broadly distributed skills because our customers may be running in very different environments or with very different infrastructure and they want skills that reflect their constraints.

So today, I pitched to our Product team the idea of upskilling our Professional Services and/or customer account teams to adapt templates we provide to create customer-specific skills to help customers with specific tasks.

Anybody out there doing anything like this yet? I’m curious how you might handle tracking where you have provided custom skills to customers for ongoing maintenance, and also success metrics around customer-specific skills. And what support and/or SLAs might look like for bespoke customer-specific skills? 🤔

I've started digging into my next agent-related research project, and it's a doozy!

Mon, 13 Apr 2026 07:34:38 -0400

I've started digging into my next agent-related research project, and it's a doozy! I've spent the last few days deep diving in 70+ docs sites, running proportional AFDocs scores based on the number of docs pages in the domain, running curated scores representing how well docs serve agents across the user journey, and spelunking in a broad cross-section of docs sites across the industry.

I've already got some interesting findings, and there will be more to come as I deep dive in the eval track...

The docs platform used makes a big difference in whether sites are agent-friendly without a lot of extra work
Web hosts and CDNs can complicate the picture
Some company/product categories are serving agents much better than others
Deep-diving in scores across this many sites has turned up 11 gaps and enhancement opportunities in AFDocs 😅

I'll be bug-bashing on AFDocs after work this week and hope to have the gaps shored up soon. And then I get to start the real fun... task design for a three-track eval project on 30+ of these docs sites to see how well the Agent Score predicts real gaps in agent task completion for the products 😁

Given the scale of this project, it's going to take a couple of months even with help... but I'll be sharing random findings along the way!

Last weekend, I started experimenting with how I might track agent website traffic

Thu, 09 Apr 2026 08:44:37 -0400

Last weekend, I started experimenting with how I might track agent website traffic. This week, someone shared my agentreadingtest.com website to Hacker News. The timing was amazing - I had already set up the site to track agent signals, and suddenly I had thousands of Hacker News site visitors pointing their agents at my site.

What a rich data mine!

I've been spelunking in the logs to try to add more agents to my tracking based on all the new data and activity I'm seeing, and I've extracted the classification logic from my metrics pipeline into a new baby library for reuse across multiple projects where I want to track this type of activity.

If you have access to log entries - either from access logs, or CDN logs - you can use this library to try to classify agent activity: agent-traffic-classifier - it's on npm and GitHub.

If you have access to the full header set, you can optionally construct "agent signal entries" - which the lib attempts to correlate with access logs to try to identify likely agent activity using stronger signal. I've also started adding in IP intelligence to help with things like narrowing down "unknown AI assistant" to, for example, Chinese assistants like Kimi or DeepSeek.

The lib is just a classifier - you'll need to do something with the data you get back. I'm just using Chart.js to build some simple charts for my needs, but you can do whatever you want with the data based on your needs.

This is a very very early brand new lib that is in no way ready to make stability guarantees or be used in production. But I built it because the companies that claim to track agent activity are not transparent in how they're doing that, so I wanted to explore how I might do that and what's actually possible. By running my own numbers, I can assess the likely accuracy of vendor solutions. If this might be helpful to you, too, feel free to play around with it. But I'm many projects deep at this point so I'm not sure this will get the same level of activity/speed of development as my other projects.

Links from the comments:

There's a lot of stuff I love about the Agent Score directory that Fern put…

Tue, 07 Apr 2026 14:54:32 -0400

There's a lot of stuff I love about the Agent Score directory that Fern put together, but in particular I think their quotes from industry leaders say better than I've been saying for the last month how wrong companies are that have been downsizing their docs teams.

This is not theoretical. These are real companies that have figured out how to measure the impact of AI agents in their conversion pipeline, and have committed to agent experience as a key business differentiator. And have connected that throughline directly to agent-readable documentation.

These folks are ahead of the curve, and their product adoption will show it. Companies like Snowflake that have dropped their entire docs team are going to see the results of these decisions and not have the foggiest idea how to measure or attribute it.

Don't be like Snowflake. Learn from the folks who are leading the pack here and figure out how to measure and apply these principles in your business.

AX is the thing.

Links from the comments:

https://buildwithfern.com/agent-score

Another busy weekend for the AFDocs tool!

Mon, 06 Apr 2026 00:48:57 -0400

Another busy weekend for the AFDocs tool! I released v0.9.0 with some additional --verbosity details on page-level checks, and support for running with a config from the command line. Define the checks you want to run in a config and easily re-run as needed while you're fixing up specific issues.

I also put together a real docs site for it, with details about the new scorecard format, how to use the CLI, using it in CI, and using the library's programmatic access. And if you're a docs team wondering what to do with all this, there's an "Improve Your Score" guide, and comprehensive per-check breakdowns to walk you through what each check means and how you can fix them.

https://afdocs.dev/

When I started building skill-validator, I didn't know I was starting a second…

Sat, 04 Apr 2026 12:56:24 -0400

When I started building skill-validator, I didn't know I was starting a second full-time job as an AI researcher and tool builder. But here we are! My little project of researching what makes a good-quality Agent Skill has turned into two tools, skill-validator and afdocs, 6 live websites + 1 WIP, and a bunch of GitHub repos backing it all.

For my weekend project, I decided to build an analytics dashboard to keep an eye on activity as my projects grow. And since I'm all-in on the AI/agent space, I wanted to elevate AI and agent traffic to first-class consumer categories alongside human viewers.

This is all totally custom logic, with no analytics platform involved. No cookies, either, so I don't have to display any cookie warnings and my analytics aren't contributing to people getting tracked across the web. I'm just pulling my server logs and parsing them to collect analytics I care about.

I'll feed my findings here back into what I'm learning about how AI and agents use the web. This gives me another view into the whole problem domain. And now I'll have my own data points to help me evaluate the claims that services are making about what their tools are capable of, and how they're seeing AI consume web content.

(Spoiler alert, I've already been keeping an eye on platforms that are incorrectly reporting/attributing things they're seeing in their data... so now I'm going to have some data of my own to tell you why they're wrong 😉 )

Instead of shoving AI into all the software that doesn't need it, can someone…

Fri, 03 Apr 2026 14:39:15 -0400

Instead of shoving AI into all the software that doesn't need it, can someone please build the collaboration tool that is missing from my workflows?

I live in GitHub, the IDE, and the terminal all day. I use AI regularly and my local files are all markdown for simplicity.

I am increasingly working with stakeholders who live in meetings all day and rely on Google docs. They need to dip in and out of content, want it to be nicely formatted so they can scan it quickly, and want a good mechanism to have discussion about specific elements.

Sure, GitHub can do all that, but my stakeholders aren't there and it doesn't fit their flows.

So instead, I'm saving Google docs as markdown, opening them in my IDE, working with them there, then copying the contents, going back to the Google doc, and pasting as markdown to update the doc.

Can someone please just make something that can sync content between Google docs and markdown on my local file system so I don't have to do this stupid dance? Ideally, it could also sync comments so I don't have to copy/paste them, too.

I would pay money for this. Enterprises would probably pay a lot of money for this.

(Editing to add, based on a lot of comments about switching to other platforms - this isn't a "switch to another platform" situation. It's a "my enterprise uses Google docs for internal collaboration" situation, and trying to get things into and out of that moat for use with my agents.)

Do your docs fill any customer support obligations?

Thu, 02 Apr 2026 16:23:42 -0400

Do your docs fill any customer support obligations? Do you have SLAs or customer agreements that require docs to be available to your customers?

Well, here's a Thursday afternoon thought exercise for you... with more and more software development being outsourced to agents, when do "agent-friendly docs" become an SLA issue? When does it start showing up in customer agreements?

I think we're very early in growing awareness of this being it's own thing to measure, but I'm really curious what y'all think about this.

(Also, good reminder you can use `npx afdocs check https://your.docs.domain.example.com to check whether your docs are agent friendly, and start thinking about what you need to do to get there.)

Oh noes

Wed, 01 Apr 2026 11:05:14 -0400

Oh noes. I just keep making work for myself. 😅

I performed an analysis of my PR review feedback (over 100 comments across 7 PRs) for the recent Agent Skills project I worked on.

Now I’ve created 12! new issues on the ‘skill-validator’ repo for checks to automate or semi-automate detection of specific patterns of issues I commented on repeatedly.

Six are structural checks:

Platform-specific tool names in the skill (not cross-platform portable)
Shell-specific commands without multi-shell handling
Flag/version/preview/beta features without stability notes
Near-duplicate text blocks within a skill
More specific token budget analysis within a skill to help authors be more efficient
Requiring eval results when an eval testing directory is present

And six are LLM-as-judge scoring candidates:

Decision tree completeness scoring
Vague instruction detection
Reference file routing quality
Flagging external links and abstract verbs without actionable next steps
Cross-file consistency checking
Detecting conditional content in SKILL.md that belongs in reference files

Once I get these checks implemented, passing the ‘skill-validator’ quality threshold will get harder. And I bet some people will be unhappy with that because skills that are passing in CI will start failing. But these all relate to real instructional quality and other quality issues that will negatively impact agent outputs.

In for a penny, in for a pound! If I can automate some of this stuff successfully, it will reduce the human review burden and improve skill efficacy for teams that don’t have a “me” in the loop 😉

The Agent-Friendly Docs Spec just got a spec bump!

Tue, 31 Mar 2026 22:59:52 -0400

The Agent-Friendly Docs Spec just got a spec bump! In v0.3.0, the spec:

Folds the standalone llms-txt-directive from the former "Agent Discoverability Directives" category into the llms.txt category, and renames it "Content Discoverability"
Adds a new "Recommended action" to each check with details about what to do to resolve a warn or failure state
Adds a new "Interaction Effects" section detailing the ways certain check failures can combine to create disproportionately worse outcomes for agents

Working on updates to afdocs now to incorporate spec updates, and I expect those to land in the next couple of days.

Excited to keep building in this space, and keep adding details to the spec as we discover more about agent docs consumption patterns. 🎉

https://agentdocsspec.com/

Really excited to celebrate the release of the official MongoDB Agent Skills

Tue, 31 Mar 2026 12:26:01 -0400

Really excited to celebrate the release of the official MongoDB Agent Skills 🎉

I had the opportunity to work with an excellent cross-functional team of collaborators to bring this initial collection of skills to your favorite coding agent.

This project has been a major proving ground for everything I've been posting about Skill development and quality. From day 1, we had CI running a structural and qualitative validator, we developed a custom review skill to help authors self-evaluate, and we had rigorous human review for technical accuracy, instructional quality, actionability, and consistency. Our contributors iterated through hundreds of review comments and multiple rounds of testing to produce this curated collection of skills.

Appreciative of all the work that all of our skill authors and contributors put in to bring you a high-quality collection! Now we get to move on to the next phase: figuring out how to operationalize contributions at this high quality bar on an ongoing basis 😁

If you give them a try, I'm curious to hear your feedback!

Sharing: MongoDB's announcement: Introducing MongoDB Agent Skills and Plugins

Thanks to a contribution from @marc0olo, the skill-validator tool can now use…

Mon, 23 Mar 2026 21:28:47 -0400

Thanks to a contribution from @marc0olo, the skill-validator tool can now use Claude Code in headless mode to do LLM-as-judge scoring! 🎉

Before this change, you could perform structural validation fast and free, but the qualitative LLM-as-judge scoring to assess your skill across multiple dimensions was only available with an Anthropic or OpenAI API key.

Now, if you've got a Claude Code subscription through work or your personal org, you can use your Claude CLI binary to perform the LLM-as-judge scoring.

One caveat: headless mode still loads your CLAUDE.md, skills, and other context, which can affect scoring output versus the bare API calls. But for folks who aren't as sensitive to the possible context pollution affecting scoring reproducibility, this feature makes LLM-as-judge scoring accessible without the extra cost of the API calls.

Available now in the v1.5.0 release.

And this is why I love open source 😁

Another busy weekend for afdocs

Sun, 22 Mar 2026 23:04:10 -0400

Another busy weekend for afdocs. The tool is up to v0.7.1 with fixes and improvements:

Many fixups for the markdown-content-parity check - turns out, comparing HTML and markdown is complicated! I'm sure there's more to do there.
Several improvements for running the tool's checks in CI:
- Implement the describeAgentDocsPerCheck vitest helper to get a detailed per-check breakdown in CI
- Improvements for config resolution and default timeouts
- A copyable example setup showing you exactly what files you need to set up the tests and CI in your project

I now have my personal website and my 4 websites for agent-related stuff all fully passing the agent-friendly docs checks! 🎉 And CI is set up to run the checks on every push or PR to main for every site to make sure they stay that way as I continue to add content.

I also did find that the markdown-content-parity check helped me identify a lot of missing content from my markdown pages. So now the markdown templates I'm using for Hugo are much more complete. 🎉

And anecdotally, while Claude was trying to identify the missing content to fix up some of my pages, it kept attempting to fetch the HTML versions of the page and being served the markdown due to content negotiation 😁 It's exactly what you want in regular usage, because the markdown is much cleaner for agents, but I had to keep telling it to curl the pages instead of fetch them as a result 😉

Another shoutout to @rhyannonjoy for contributing more known platform limits to…

Sat, 21 Mar 2026 15:57:15 -0400

Another shoutout to @rhyannonjoy for contributing more known platform limits to the Agent Friendly Documentation Spec!

This time, Rhyannon dug into Cursor. Reading their writeup of the methodology reveals a lot of assumptions we're probably all making about how agents fetch data: https://rhyannonjoy.github.io/agent-ecosystem-testing/docs/anysphere-cursor/methodology

(And spoiler: we're probably wrong about at least some of them!)

And the friction log reveals how complicated it can be to test these things.

Super appreciative of their work here. Rhyannon has become a substantial contributor to the spec at this point with all the deep dives on platform-specific findings, and if you have been wondering how to test things like this, their site is a great learning resource.

Really grateful to have them along on this research journey!

If you're publishing Agent Skills for others to use

Sat, 21 Mar 2026 14:24:28 -0400

If you're publishing Agent Skills for others to use: do you know what happens when your skill loads on a platform you haven't tested?

The Agent Skills spec defines a portable format. Write a SKILL.md once, users install it anywhere. Over 25 platforms support it. But "support" covers a wide range of actual behavior. Your skill's reference files might load automatically on one platform and be invisible on another. Your frontmatter might reach the model on one platform and get stripped on another. Your instructions might survive a long conversation on one platform and get silently pruned on another.

The spec's implementation guide says "every skills-compatible agent follows the same three-tier loading strategy." That guide was based on analysis of 7 platforms. At least 25 had shipped their implementations before it was published.

We don't actually know how most platforms handle skill loading. Nobody does. So help me find out!

I've started a community research project cataloging 22 loading behavior checks across 9 categories: loading timing, directory recognition, resource access, content presentation, lifecycle management, access control, structural edge cases, skill-to-skill invocation, and skill dependencies. The repo includes 16 benchmark skills with embedded canary phrases that reveal exactly what a platform loaded and when, without relying on model self reporting.

What we need now is people testing on real platforms. If you use Agent Skills on any platform (Claude Code, Cursor, GitHub Copilot, Roo Code, or any of the others), you can run the benchmark skills and submit your findings. Even partial results from a single platform are valuable. One empirical observation beats a hundred assumptions.

This is community science for the agent ecosystem. The findings will be published at https://agentskillimplementation.com and the full project (benchmark skills, test procedures, results template) is on GitHub: https://github.com/agent-ecosystem/agent-skill-implementation

If you're distributing official skills and care about them working across platforms, this is directly relevant to you. And if you've already noticed your skills behaving differently on different platforms, your observations are exactly what we're looking for.

I have been seeing posts from folks about Snowflake laying off its entire tech…

Wed, 18 Mar 2026 11:04:15 -0400

I have been seeing posts from folks about Snowflake laying off its entire tech writing team. This is an absolutely bonkers decision for any org to be making today.

Your technical writing team is how you ensure that people can discover and learn your products. And the content flows across many systems.

It’s not just humans reading the docs, and hasn’t been for years. Model providers crawl docs to train their models on your products. Coding agents refer to your docs in-process to perform coding-related tasks for developers. Documentation is an essential resource for all of these systems.

Forward-thinking orgs understand this and have been building feedback loops to evaluate how well these systems understand products from the docs, and make targeted updates to docs to improve how the information flows across these systems. Docs are more important than they were when it was just humans reading them, not less. Humans could adapt to poor documention and sometimes succeed in spite of it. Today’s systems can not.

Any company that cuts its entire documentation team is telling me it does not understand how product discoverability and agent-first developer workflows work in today’s world. It is telling me that I should switch to a company that understands these things because my tools need high-quality, well-maintained documentation to succeed at the tasks I need to achieve.

Busy weekend for Agent-Friendly Docs!

Sun, 15 Mar 2026 22:04:54 -0400

Busy weekend for Agent-Friendly Docs!

I added a new check to the spec, rendering-strategy, which checks whether a docs site renders content that is visible to tools like Claude Code and Cursor that use fetch library implementations instead of embedded or headless browsers
I updated spec pass/warn/fail details based on practical details discovered during implementation
I completed implementing the remaining checks in the afdocs CLI and library available through npm 🎉 All 22 checks are now fully implemented.

If you have Node.js/npm installed, you can run the tool locally to check your docs site for agent-friendliness:

npx afdocs check https://docs.example.com

The tool is now at v0.5.0; I'm going to leave it a v0.x tool for a bit longer while I wait to hear any bug reports from folks who are trying it out. Depending on how much feedback I get, and my own experience using it, I'm hoping to cut a 1.x release in April.

If you try it out, please do file any issues with bug reports or request enhancements on the tool repo. I'll throw links in the comments.

Links from the comments:

Two more checks implemented in v0.4.0 of the afdocs npm package!

Thu, 12 Mar 2026 07:58:55 -0400

Two more checks implemented in v0.4.0 of the afdocs npm package! 🎉 This brings the tool up to 16 of 21 checks implemented.

If you haven't seen it yet, afdocs is a TypeScript CLI and library available through npm to help you check if your docs are agent-friendly. It implements checks against the Agent-Friendly Docs Spec, giving you immediate signal on where your docs are already agent-friendly, and where you could make enhancements.

The two new checks I've added in this version are:

redirect-behavior: checks how redirects are implemented in your docs, and warns or errors if they're implemented in a way where agents may not be able to follow them
llms-txt-directive: checks both your HTML and markdown pages to see if they have a hidden directive referring agents to an llms.txt file. This can help agents find agent-friendly content, like markdown instead of HTML, or serve as an index for agents to find related or relevant pages

If you've got Node.js/npm installed, you can run the tool on any docs site today with this command:

npx afdocs check https://docs.example.com

Just change the docs.example.com link to your docs site and give it a try! It samples random pages to give you info about how agent-friendly your docs are. You can specify how many pages to sample with the --max-links option; it defaults to sampling 50 pages.

You can also use it as a library to help define tests for agent-friendliness that you can run in CI.

I'll throw a link to the package on npm in the comments if you'd like to learn more.

Links from the comments:

https://www.npmjs.com/package/afdocs

I’ve started reviewing some draft agent skills, and am learning a few things…

Wed, 11 Mar 2026 07:39:45 -0400

I’ve started reviewing some draft agent skills, and am learning a few things about optimizations we can make:

If a skill has prerequisites that are implicitly stated somewhere in the skill body, move them to the top and explicitly state them as prerequisites. Provide a scope gate with instructions for how the agent should handle missing prerequisites. Should it prompt the user? Attempt to install something on its own? Take some local action to resolve the missing prerequisites?
If a SKILL.md contains info that is only needed conditionally, consider moving it out of the skill body and into a reference file in ‘references/‘. Agents load the entire skill file into context every time it’s invoked, and if part of the content is not required for every invocation, you’re wasting context with information that only applies conditionally.
If your skill relates to something that’s behind a feature flag, consider what happens if the feature flag is removed. Is the skill written in such a way that it’s still useful? Are there instructions for the agent about what to do once the feature flag is no longer there? Will it the skill need to be updated or removed, and do you have a way to let your users know when that needs to happen?
Is your skill or any reference content tied to information that is maintained somewhere else? If so, changing the information in the other source should trigger a skill update. You need to have processes in place to watch external sources of truth and alert you when skills need to change.

If you’ve been creating or reviewing agent skills recently, any other optimizations you’ve spotted that we should be thinking about? 🤔

Another shout-out to @rhyannonjoy for contributing more known agent platform…

Tue, 10 Mar 2026 06:41:52 -0400

Another shout-out to @rhyannonjoy for contributing more known agent platform limits to the agent docs spec! Rhyannon has been systematically testing some of the other tools, and with their recent spelunking into Google Gemini, the picture has gotten even murkier for agent docs access.

Gemini works differently than some of the other agent platforms, and Rhyannon's observation here has implications for understanding how Gemini "sees" our docs:

There’s no direct equivalent to the Claude API web fetch track’s character-level truncation measurement. The API doesn’t expose the text injection or where truncation occurred.

The takeaway is that with the way the Gemini API works, there isn't a way for us to get clear visibility from the API side into what the agent retrieves, and where or if a truncation boundary may exist. It's not as simple or clear as knowing Claude Code or the Claude API truncates at X characters.

It's probably possible to do some observed testing; give Gemini URLs for pages with different lengths, and ask about content on different parts of the page to determine what Gemini "sees."

But the fact that there isn't a straightforward way to discover this information underscores the challenges we face as documentarians - what is true for one platform may not be true for others, so the question of "how well can agents use our docs" has a qualifier: "which agent?" For docs teams, the question in the short term may be "which agent platforms are most of our customers using?" and trying to optimize for that, instead of trying to generalize rules that work for all agents.

Anyway, big shout out to Rhyannon for continuing to explore this and sharing their findings back to the Agent-Friendly Docs Spec so we can all benefit! 🎉

I'm also really enjoying the write-ups of their research - I'll throw a link in the comments if you're curious about this stuff the way I am. 😁

Links from the comments:

https://rhyannonjoy.github.io/agent-ecosystem-testing/

Agent Skills provide a great way to give your agent reusable workflows…

Mon, 09 Mar 2026 07:29:54 -0400

Agent Skills provide a great way to give your agent reusable workflows, information about up-to-date product details, or custom domain knowledge. But my audit of 673 agent skills last month found that 22% fail basic structural validation, and 52% of tokens across these skills were in non-standard files potentially wasting your agent's context.

In short, there's a real quality gap in published agent skills. And using skills that don't meet minimum quality standards can actually degrade your agent experience. So I wrote skill-validator to help people assess their skills.

As I've been socializing skill-validator with people creating skills, I realized some skill authors may need additional help interpreting the output or figuring out what changes to make to improve their skills. So I've added some examples of tools I've created to help authors ensure their skills meet a minimum quality bar to the skill-validator repo:

A review-skill skill that instructs an agent how to run skill-validator, interpret the results, and provide actionable feedback to skill authors
A CI workflow that runs structural validation checks on PRs with new or changed skills, and fails CI for skills that don't meet structural quality requirements, potentially blocking merge

Whether you're adding your own or someone else's skills to a project, or publishing official company skills for customers to use, these tools can help you ensure the skills you're consuming or producing meet minimum quality requirements.

Links from the comments:

https://github.com/agent-ecosystem/skill-validator/tree/main/examples

If you like to take concrete actions to support causes, there's something you…

Sun, 08 Mar 2026 11:45:25 -0400

If you like to take concrete actions to support causes, there's something you can do today to help women succeed: join Kiva, and fund micro-loans to help women grow businesses, bring much-needed community support programs to their communities, or make lives more sustainable for them and their families.

I've been a Kiva member since 2013, and here are some of my stats:

I've helped fund 242 loans
I've lent to 34 different countries and territories
I've helped women fund agriculture, bakeries, convenience stores, grocery stores, computer services, and other much-needed services in their local communities
I have lent almost exclusively to women, because as a woman, my goal with these micro-loans has been to help lift women up

When funds are repaid, you can re-lend them to keep the cycle going. So you can start with a small contribution and grow your impact over time. I usually re-lend when I've got $50-100 in repayments accumulated in my account, and I add another $50-100 of my own, which grows the impact I can have year-over-year without being unsustainable for me.

I'll throw a link in the comments to a special Kiva is running today - support a woman and get an extra $20 to lend.

Links from the comments:

https://www.kiva.org/lend-by-category/women

Last weekend, I set up a Digital Ocean droplet to serve as a self-hosted runner…

Sun, 08 Mar 2026 09:58:00 -0400

Last weekend, I set up a Digital Ocean droplet to serve as a self-hosted runner for some GitHub CI I wanted to run in private repos in the new org I set up. I also set up Cloudflare Pages to host a site behind a GitHub App auth login so only people in my org can access it.

This weekend, I’ve added a FastAPI server to my Digital Ocean droplet to host a form. It’s got a Cloudflare tunnel to the site that’s behind GitHub App auth login, and I’ve slightly complicated deployment to make it more secure.

I do not have a DevOps background, but that doesn’t stop me with Claude’s assistance. BUT Claude’s DevOps guidance was not secure by default. At every step of the way, I’ve had to ask about possible attack vectors and how I can make the infra more secure. I’m sure I’ve missed things because I don’t have a DevOps background, even with asking about various security angles.

For my project, the exposure risk is pretty low. It’s really not the end of the world if anyone gets access to the data I’m working with. It’s all for internal/private use - I’m not working with customer data or selling a service.

But these projects have given me anxiety about all the new services folks are spinning up. I have to ask myself how many other people who don’t have DevOps backgrounds are now standing up infrastructure with the help of coding agents and are not asking the security-related questions. I admit, I’m probably going to hesitate now before signing up for someone else’s new service if it needs PII, payment info, or any data I don’t want exposed.

Also, this weekend Claude wrote a few additional details about me to its persistent memory… “prefers vi editor” (when I’m ssh-ing onto a remote server and the default editor is nano, I’m lost!) and “security-conscious.”

Ok, Claude, I think that’ll be helpful. 👍

Links from the comments:

https://www.kiva.org/lend-by-category/women

Taking a minor break from agent-related research - sort of - to fix up some…

Sat, 07 Mar 2026 21:37:05 -0500

Taking a minor break from agent-related research - sort of - to fix up some issues and feature requests for my newest macOS app that's in TestFlight Beta - Issuenator.

I've accumulated... kind of a lot of repos where I want to keep tabs on issues. And sometimes I file issues on other people's repos. And at work, I have a separate set of repos where I want to watch issues.

So in the spirit of PR Focus, my PR-tracking dashboard, I created Issuenator - an app for keeping track of all the issues across all the repos I care about.

I intentionally kept it separate from PR Focus because I'm really in different workstreams when I'm handling these things. PR Focus is for keeping track of my day-to-day work, and what my colleagues need from me. Issuenator is for keeping track of incoming requests from outside folks. I usually check on Issuenator at the beginning and end of the day to check for new issues or issue updates, or occasionally when I'm swapping between tasks, but otherwise don't want the noise interrupting my main workstream.

If you're a maintainer on a lot of repos, or if you file issues on a lot of repos, and you've ever wanted to keep track of all the issues in one place so nothing gets forgotten, maybe you want to give this a try. I've been in private beta for a couple of months and am pretty satisfied with the current state, so I'm thinking of opening it up to a public beta soon. If you want to try it out for free before I launch it, let me know.

https://issuenator.app/

I love my friends

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

I love my friends. And I know they care about me. But right now I have some things coming into focus with a clarity that demands action.

I'm spending basically every non-work hour exploring those things. I'm staying up too late. I'm getting up too early. I know I can't keep up the pace, but at the moment, the exploration is exhilarating. Sleep seems like an afterthought. I'm chasing things because they're interesting and because they feel important. And it feels like something I'm good at - like I've leveled up and unlocked a new mode that lets me do all the things I've enjoyed in bits and pieces, all at once, for a united purpose.

So it's hard when friends see me so excited, but the response is to throw buckets of cold water. "Dose of reality" they say. "What makes you think other people with more resources and a head start aren't already working on these things?"

I'm sure they are. But I also think that my take matters, too.

I have no idea what, if anything, will come of it. But that's not the important part. The important part is doing something I'm excited about because I'm excited about it, and because I think it matters.

Mostly sharing this to remind me it's ok to calibrate my risk tolerance and priorities differently from my friends. And maybe someone else needs to hear this right now, too.

If you've been following along on my Agent Skill exploration, you've probably…

Wed, 04 Mar 2026 07:28:25 -0500

If you've been following along on my Agent Skill exploration, you've probably seen me post about my skill-validator tool. I wrote it to help with my Agent Skill Report, and I've been quietly polishing away at it alongside all the other agent-related stuff I've been doing.

Last night, skill-validator got a new home and a v1.0.0 release! 🎉

The skill-validator tool now:

Has separated core logic into library functionality to support reuse in other contexts, like test suites and other tools
Retains the CLI entrypoint, but at a new location
Lives alongside other tooling and resources I'm building related to agent things, in the GitHub agent-ecosystem org

If you've been using skill-validator via brew, you'll need to tap the new homebrew tap to get 1.0.0 and future updates:

brew tap agent-ecosystem/tap brew install skill-validator

I've got a lot more plans in mind for this tool, so if validating skill spec compliance + getting some quality checks is something you're interested in, keep an eye out for future updates. 😁

Links from the comments:

https://github.com/agent-ecosystem/skill-validator

Big shout out to @rhyannonjoy for contributing a new set of known platform…

Mon, 02 Mar 2026 23:58:47 -0500

Big shout out to @rhyannonjoy for contributing a new set of known platform truncation limitations to the Agent Friendly Docs Spec!

Rhyannon used some Python-foo and the same data I used in my Agent Web Fetch Spelunking article to test the limits of the Claude API with the web_fetch tool enabled - similar to, but not the same as, the Claude Code web fetch implementation.

I'm sorry to say the results do not bode well for the average documentation page, friends. 😰 My initial findings with the Claude Code web fetch + summarization model were much more generous than the Claude API's web fetch default truncation limit.

What this means is that anyone who's built something that uses the Claude API/Claude platform - including possibly repackaging Claude in other agent tooling - may have far more aggressive truncation limits. Which means even less of our docs content may be making it through than I initially thought based on Claude Code.

Help us do science to it! Check out Rhyannon's PR, which I'll link in the comments, for an idea of how we can approach these problem domains.

Pick something you're interested in learning more about, do some testing, and share the results! We will all benefit.

(And if you contribute back to the Agent-Friendly Docs Spec with your findings, we can keep building out the constraints so we can adapt our docs systems to serve them.)

Links from the comments:

https://github.com/agent-ecosystem/agent-docs-spec/pull/2

New project!

Sat, 28 Feb 2026 23:33:59 -0500

New project! I'm accidentally deep in coding agent land now, so I'm starting a new site - aeshift - a commentary and analysis blog about the agent ecosystem.

This one is a fun experiment for me because it's a different voice, with a very specific lens - practitioner-focused - and I'm using agents to help me with the content sourcing and draft pipeline.

I've already learned a ton just in putting this together, which I'll write about separately on my normal blog. But if you're on the dev/engineering side of the house and want to keep up with agent ecosystem developments and their practical implications, it might be worth a follow!

(Also, for the folks who have seen me posting lately about agent-friendly docs - yes, I've used my tooling and this site passes 100% of my agent-friendly docs checks 😁)

Links from the comments:

https://aeshift.com

I've been chatting with a lot of technical writers and docs orgs as a result of…

Thu, 26 Feb 2026 08:38:45 -0500

I've been chatting with a lot of technical writers and docs orgs as a result of the recent work I've been doing with the Agent-Friendly Docs Spec and the afdocs tool to validate docs against the spec.

Some folks have been concerned that this looks like a big project and they don't have the time or resources for it. But the reality is, it can look as small or as big as you want it to depending on how much this matters to you right now.

Some folks I've been chatting with have made one or a handful of fixes to their docs. Even just small changes can help.

If you can only do one thing right now, start with page size. The three checks you care about are:

page-size-markdown: If the character count in markdown is too long, the content gets summarized and the agent will never see the full page. Long API references are likely to fall into this category. Break them up into smaller pages so the agent can actually see the content, instead of a summary that may miss important details.
page-size-html: HTML adds more content with less semantic value for the agent, and may hide content away through JS elements. Your HTML pages are probably much longer than a markdown page would be and more likely to trigger summarization. Work with your platform to reduce the HTML page size, or add agent discoverability directives to point agents to the markdown version of your pages. (Or both!)
content-start-position: This mainly applies to pages in HTML; depending on how the agent platform handles the HTML -> markdown conversion, some agents will never see your page content. Try to get your actual documentation content to start as close as possible to the beginning of the page content. In my experimentation, I found one page where the content was only ~60 lines and it started 87% of the way through the page. That's a big problem for agents.

Try out these checks for yourself using the afdocs CLI and lib you can install through npm. See how your docs actually perform, and check regularly as you iterate to make improvements.

And let us know what fun and interesting things you run into along the way! The platform providers aren't incentivized to study these things, or tell us about them. So we need to figure out the edges ourselves and share with each other so we can all prepare for this new type of docs consumer together.

This is what it looks like to be doing the work

Tue, 24 Feb 2026 22:41:37 -0500

This is what it looks like to be doing the work. Mintlify's own docs set - a docs platform whose premise is "built for both humans and AI" - passes all the Agent-Friendly Docs checks I've implemented so far, save one.

Mintlify's docs return "soft" 404s (returning a 200 with "no content" for a page that doesn't exist instead of a clearly actionable 404). But this is pretty minor, easily fixed, and would only affect a small subset of content in practice.

The fact that they're already doing all the things I identified as important for agent friendly docs means they - and their customers - are ahead of the curve. This is how you spot the real deal, folks.

(Also, now I have a "known good" docs set to test my tooling against as I continue to add checks 😁)

Just pushed another batch of updates to the afdocs tool that enables you to…

Tue, 24 Feb 2026 09:08:31 -0500

Just pushed another batch of updates to the afdocs tool that enables you to test your documentation site against the Agent-Friendly Documentation Spec. The v0.3.0 update adds the remaining 4 full-automated checks with clear pass/warn/fail conditions, bringing it up to 14 of 21 checks implemented. The new checks are:

markdown-code-fence-validity: if you have unclosed code fences, agents will interpret any content after the opening code fence as code, leaving the content subject to misinterpretation
http-status-codes: whether error pages return appropriate status codes, or "soft" 200 on 404s that may confuse agents
cache-header-hygiene: can agents see fresh data, or are you setting long caches that mean agents may get outdated information?
auth-gate-detection: do documentation pages require authentication to access content? If so, can agents figure that out, or is the type of return response ambiguous

The remaining checks are more subjective and open to different interpretations. I'll implement heuristics that make sense to me given the behavior I've observed, but your organization might care about or want to measure those things differently. Feel free to comment on the Agent-Friendly Spec repo to discuss what implementation might look like to you, so we can consider codifying more details in the spec.

Package on npm: https://www.npmjs.com/package/afdocs

Links from the comments:

https://github.com/agent-ecosystem/agent-docs-spec

Because a couple of folks have asked or commented, some more thoughts related…

Tue, 24 Feb 2026 06:35:13 -0500

Because a couple of folks have asked or commented, some more thoughts related to the markdown content that features heavily in the Agent-Friendly Docs Spec:

Where I talk about markdown in the spec, I'm talking about it as an output format for your docs pages. The input format doesn't matter so much. You can write in reStructuredText, MDX, or whatever format makes the most sense for your docs. But agent-friendly docs offer markdown as an output format for the docs pages to be consumed by agents, which work far better with markdown than HTML.
I am not proposing that you maintain a second source that's in markdown alongside whatever source you already maintain. Ideally, your build pipeline automatically generates markdown versions of docs pages.
Given that I expect the output markdown to be auto-generated, this is a big part of why I proposed the markdown/HTML parity check in the Observability section of the spec. I have seen in my investigation real-world cases where the markdown generation process is stripping text on the markdown versions of the pages that is rendering correctly on the human-viewable HTML versions of the pages. This includes things like parameter names, contextualizing headers and intro sections, and other information that the agent needs and isn't getting. The failure mode is this: human looks at page rendered in HTML, content is there, human doesn't look at markdown page and doesn't notice content is missing.

There are probably more things related to this that I'll discover as I continue to dig deeper. But I'm curious if any of y'all have started looking at your own generated markdown as a result of the spec and these convos and noticed anything else we should be thinking about?

Now that I'm starting to understand what it means for docs to be agent…

Mon, 23 Feb 2026 09:15:29 -0500

Now that I'm starting to understand what it means for docs to be agent friendly, I'm charging full steam ahead with tooling to support this important docs consumer. If you want to check how agent-friendly your docs are, you can use this new tool I'm developing and distributing through npm: afdocs

It's a CLI/library that implements the Agent-Friendly Docs Spec and is distributed via npm. Currently, only the first three check groups are implemented, but I think those are some critical entry point checks that have real value today and don't want to delay release until the entire spec is implemented. You can run checks for:

llms.txt (5 checks) - llms-txt-exists: Can agents find your llms.txt? Checks candidate locations so agents have a starting point for your docs. - llms-txt-valid: Does it follow the proposed structure from llmstxt.org? Malformed files mean agents can't parse your doc index. - llms-txt-size: Will it fit in an agent's context window, or will it get truncated before the agent sees everything? - llms-txt-links-resolve: Do the URLs in llms.txt actually work? Broken links send agents into dead ends. - llms-txt-links-markdown: Do those links return markdown? Agents work much better with markdown than raw HTML.

Markdown Availability (2 checks) - markdown-url-support: Can agents get markdown by appending .md to page URLs? This is the simplest way to serve agent-friendly content. - content-negotiation: Does the server respond to Accept: text/markdown? A standards-based alternative to URL conventions.

Page Size (3 checks) - page-size-markdown: Are your markdown pages small enough for agents to consume without truncation? - page-size-html: How large are your HTML pages, and how much shrinks away when converted to markdown? High boilerplate ratios waste agent context or may mean docs are summarized instead of read verbatim. - content-start-position: How far into the page does the actual content start? Navigation, headers, and boilerplate at the top push real content past truncation limits.

That's the 10 implemented checks. The remaining 11 are stubbed across content structure, URL stability, agent discoverability, observability, and authentication categories. I'll be continuing to build these out in the coming weeks.

Link to package on npm: https://www.npmjs.com/package/afdocs

How do we move forward as a documentation community to create agent-friendly…

Sun, 22 Feb 2026 08:16:15 -0500

How do we move forward as a documentation community to create agent-friendly docs that the new era of coding agents can consume and benefit from?

We make a spec! And we implement tools that can validate our docs against the spec.

I'm proposing the Agent-Friendly Documentation Spec - at the time of writing this post, it's 21 checks across 8 categories, but I keep adding new ones 😁

This is my attempt to turn observation and research into the minimum, practical, mechanical guidelines required to make docs agent friendly across these categories:

llms.txt
Markdown availability
Page size
Content structure
URL stability
Agent discoverability
Observability
Authentication

I'm sure there are more things I haven't considered yet, so help me brainstorm, technical writing hive mind... what else should be here? The website links to a GitHub repo. Please file issues and let's start talking about how this can serve all of us as we look to make our docs more coding-agent-friendly.

https://agentdocsspec.com/

Ok, lunch thought and I'm curious for your input, Technical Writers - no wrong…

Fri, 20 Feb 2026 13:38:07 -0500

Ok, lunch thought and I'm curious for your input, Technical Writers - no wrong answers here.

So far, as I've been digging into agent-friendly docs, I've been focusing mostly on static analysis - what can we measure - to derive some early findings and focus initial exploration.

But at lunch, I started thinking - what does "developer documentation" look like in 2 years? 3 years? 5 years?

Where do we draw the distinction in writing for developers - i.e. the agents - and writing for the humans running the agents? Are these distinct personas that require their own documentation sets? What belongs in each? And how do we serve the industries where regulation or other limits constrain their AI usage?

What do you think? Let's brainstorm!

I've done a deep dive analyzing the Agent Skills ecosystem around modular…

Tue, 17 Feb 2026 09:56:02 -0500

I've done a deep dive analyzing the Agent Skills ecosystem around modular instruction packages that tools like Claude Code, GitHub Copilot, Cursor, and 27+ other agent platforms use. These packages are intended to extend what coding agents can do with custom instructions covering specific domain expertise.

I looked at 673 skills from 41 source repositories. Some things I found:

- 22% of published skills fail structural validation — including skills from companies like Microsoft and Stripe - Over half of all tokens contained in Skills are nonstandard files (LICENSE texts, XML schemas, benchmark data) that provide little or zero value to the agent - Most skills just restate what the LLM already knows. My analysis indicates that novelty is the weakest quality dimension across the ecosystem, and the most important one. Novelty is information the model can't derive from training data. - 66 skills look clean on the surface but carry hidden potential for contamination in their reference files

I also ran a behavioral eval to see whether structural risk scores actually predict degradation in agent output. They don't (r = 0.077). The real interference comes from content-specific mechanisms: template syntax bleeding into output, framework-specific patterns leaking into unrelated tasks, and API hallucination where the model invents plausible but nonexistent SDK methods.

I published an interactive report where you can explore every skill individually; validation status, quality scores, contamination risk, token breakdown; along with the full paper:

https://agentskillreport.com/

If you're writing or using Agent Skills, the practical takeaways: - Run skill-validator before publishing - Focus on what the LLM doesn't already know - Clean nonstandard files out of your skill directory - Scope skills to a single language SDK when possible

I'm working on a weekend project that requires an LLM to go read hundreds of docs links

Sun, 15 Feb 2026 15:58:07 -0500

I'm working on a weekend project that requires an LLM to go read hundreds of docs links. And I am very dismayed by the state of docs for LLM consumption. I've been a little spoiled by being able to point LLMs at Markdown versions of docs pages for some of the bigger or more modern platforms, and it's a bummer how much software out there does not provide LLM-friendly documentation.

I keep falling back to GitHub repos, and specifically the raw versions of code and markdown files, and it works like a charm.

As an industry, if we can't figure out a way to elevate LLM/agent users to first-class consumers of our docs, we're just going to lose them entirely. "Skip the docs and refer to source" might become my first instruction instead of a fallback.

Oh noes

Fri, 13 Feb 2026 21:17:36 -0500

Oh noes.

I have set up an evaluation system to score LLM outputs for code gen tasks involving our products, which I’ve planned to use to validate any Agent Skill content we create.

For my first test case, the Skill content made the output worse than the unassisted LLM performance. 😬 🙃

We support 12 programming language drivers, plus a shell tool and some other interfaces.

Turns out, when you shove a code example in front of an LLM, it really wants to mimic that code example, even if it’s for a different programming language. So agents that can write the code perfectly fine from base training data actually mess it up when they see a “wrong” example in context.

For products that support a lot of languages… I’m wondering if this will require language-specific Skills? 😰 😱

Also, the code example patterns that we show in docs, which are written for humans to learn from - not intended to represent production code… yeah, maybe those are the wrong examples for LLMs. 😕

This is going to be an interesting learning curve…

Agent Skills are the new hot topic as AI-assisted engineering practices shift…

Thu, 12 Feb 2026 19:02:12 -0500

Agent Skills are the new hot topic as AI-assisted engineering practices shift from prompt-focused to context-management.

To me, that means content governance and the content management lifecycle are back in vogue.

Nobody with experience managing content wants to maintain a duplicate source of truth. PostHog shared an article recently about an AI Wizard they created, and one of the problems they cited was drift between the maintained source of truth - docs and the product - and the AI Wizard content. Now picture that at scale across a bunch of different Agent Skills, most of which are duplicating content that already lives in your docs.

Some folks are solving for this by pointing LLMs at docs and saying “make this a Skill!”

Don’t do that.

Probabilistically copying your docs through an LLM is a recipe for omissions and conflation. And when you need to do it again in a month or 6 months when the product changes, you will get completely different outputs. It’s probabilistic.

Instead, beg, borrow, steal, or vibe-code your own system to deterministically create Skills from your docs source. That way, you can regenerate it as often as you need to as your product evolves, without maintaining a second source of truth or relying on a probabilistic system that will create unsustainable review and maintenance overhead.

Had a fun little project today

Mon, 09 Feb 2026 18:27:04 -0500

Had a fun little project today: I put together a proof-of-concept for evaluating AI code gen for a task related to our product across various LLMs with a handful of inputs:

Baseline: “basic” prompt only, no help
With docs: same “basic” prompt, plus read in the content from a relevant documentation page
With Skill: same “basic” prompt, plus read in the relevant content from a targeted AI Skill

I’m trying to validate whether:

Unassisted LLMs can successfully perform code gen tasks for our product
Adding a relevant documentation page produces an improvement in the output
Adding a targeted Skill produces an improvement in the output, and if so, how that compares with the “With docs” version

The results were… unexpected! There’s definitely going to be a blog post about this soon.

One of the writers in the org just reported an issue with my tooling, which…

Mon, 02 Feb 2026 16:55:54 -0500

One of the writers in the org just reported an issue with my tooling, which prompted me to look at our running GitHub Actions and I saw a sea of red.

Ran this little ghok command line utility (GitHub, are you OK?) and I can see there are active incidents affecting GitHub Actions.

Good reminder that having little utilities like this that meet you where you are make all the difference. I never have to look up the GitHub status page, or bookmark it, and wade through reports - just type a few characters into one of the many terminals I have open at any given time and see output like this.

If you are a technical writer who sometimes uses the command line for things, I cannot recommend enough starting to customize the utilities available to you to make your life a little easier. Before long, you will build up a library of useful things and wonder how you ever did anything without them.

Links from the comments:

https://github.com/abennett/ghok

Heya #TechnicalWriting hive mind - I am curious for your thoughts!

Mon, 02 Feb 2026 15:58:06 -0500

Heya #TechnicalWriting hive mind - I am curious for your thoughts!

I've been thinking a lot lately about the intersection of docs, AI skills, and custom agents as it relates to content reuse.

The name of the game in AI-assisted anything these days is context management. You don't want to blow up your context with an overly-verbose documentation page - or Skill file - and let's not even talk about handing an LLM an entire section of your docs.

I've been pondering how we can make our content more modular to enable just-in-time context discovery for LLMs. Sure seems to me like a new take on an old trick - DITA - but I'm not seeing anything like this implemented anywhere yet. Are you aware of any companies that have successfully modularized their docs content to support reuse in different AI contexts?

I've tried things like Skill Seekers to create Skills from docs content, but the verbosity is an issue. We really need much smaller chunks to right-size content to fit into a context window without overwhelming it, while human readers may have different preferences (fewer clicks, larger pages).

If you know of any company that is successfully doing something like this right now, please share!

Links from the comments:

https://github.com/abennett/ghok

Yesterday was my 5-year anniversary at MongoDB

Wed, 21 Jan 2026 08:15:15 -0500

Yesterday was my 5-year anniversary at MongoDB 🎉

A lot has changed in 5 years. I was hired as the first non-developer on a team of developers documenting a DB that MongoDB had acquired. I learned Swift and released my first iOS app using our product. I learned C++ and wrote a TUI sample app for the product. Along the way, I embraced testing tools and drove IA initiatives that improved DX and feature discovery for our products.

After the product was sunsetted, my team pivoted to bringing programmatic standards, testing, and strategy to the larger org. On an average day, I’m far more likely to be writing code than docs, although I still do both. Internal tooling and enablement has become my happy place, all with the purpose of making our programmatic experience world class for both developers and robots.

Leadership at MongoDB talks about how they want working here to be an inflection point in people’s careers, and it has definitely been that for me. I’m doing the most interesting work I’ve done in my career, with a team of people who are a delight to work with.

I feel I’ve been blessed in this role, and I hope for many more years helping transform how my org - and the industry as a whole - handles programmatic user experience in docs.

I think one of the things that makes me good at development work is the amount…

Wed, 07 Jan 2026 14:04:56 -0500

I think one of the things that makes me good at development work is the amount of context I can hold in my head at once. Generally, I can maintain mental mapping for a lot of state at once. That helps me better understand and visualize complex systems, and consider aspects of how they interact.

At the moment, this is also a valuable asset for AI-assisted development. Even the best models just cannot hold the context I can manage in my head. So after I get working code, I go through and validate all the context correctness across the new code. I remind AI to use constants we’ve already defined, refactor shared logic to internal packages, handle business logic appropriately, and account for the many many edge cases I know we have that AI doesn’t know or understand.

It’s never going to one-shot complex functionality that requires a lot of context. That’s where I come in.

I expect that will change as models and context management strategies continue to evolve. But at the moment, I’m sitting with the knowledge of all the work I still have to do after the AI is “done” before something is ready to ship.

Yay, my remaining Christmas gift for wifey is live on the App Store!

Tue, 06 Jan 2026 21:52:23 -0500

Yay, my remaining Christmas gift for wifey is live on the App Store! 🎉 🎊 🥳

For Christmas this year, I finally finished the tea tracking app I started writing for her years ago. If you're a tea enthusiast, maybe you'll find it useful, too!

(Yes, I also have a coffee-themed version of this in progress for me... whenever it makes it back to the top of the todo list.)

https://tealixir.app/

As 2025 draws to a close, it's a natural time to reflect

Wed, 31 Dec 2025 16:56:51 -0500

As 2025 draws to a close, it's a natural time to reflect.

It has been a challenging year for many people, and my family has faced our own share of challenges.

But I end the year grateful to be a part of a team of people I enjoy working with every day, who support one another throughout our challenges. And I am so happy to have a job that lets me tackle interesting problems and provide value in ways that are meaningful to me.

My role has undergone a transformation from 2024, where my primary role was documenting a database product. Instead, I've become a Developer Documentation Code SME for all things code-example-related. My day-to-day work is now a split between software engineering and writing documentation for internal stakeholders:

Helping leadership make decisions about code-related considerations.
Helping the members of the technical writing organization leverage the new tools we're providing.

I'm really enjoying the software engineering work. And I also feel valued for my ability to create effective and actionable internal docs.

Value alignment is one of the keys that enable me to remain highly productive over a long period of time while avoiding burnout. The value alignment in my current role is particularly important for me as an employee.

Here's to 2026 - may it bring a new array of interesting problems to tackle!

Well, thanks to @caseyrfsmith 's urging, I've been trying out Claude Code for…

Sun, 28 Dec 2025 12:52:29 -0500

Well, thanks to @caseyrfsmith's urging, I've been trying out Claude Code for the last few weeks... I've just canceled my Augment Code account.

Augment was good, but after they switched to credits-based pricing, I was basically using my entire monthly allotment in two days.

I was afraid that using Claude directly, I would hit my rate limit for each 5-hour session or weekly limit and be out of luck. Compared to Augment, though, having to wait for a 5-hour session or even a weekly session to reset is better than only getting to use my tool 2 days per month.

So long, Augment Code. 🫡

My team has been working across a lot of different repositories lately, so I've…

Mon, 15 Dec 2025 10:52:22 -0500

My team has been working across a lot of different repositories lately, so I've set up my PR tracking app, PR Focus, on my new work computer.

It flagged ~5 PRs that needed attention across the 11 repositories my team works in, and I was able to take action on those PRs.

It has also made my team's work more visible in the very active monorepo we work in daily - the monorepo averages ~260 open PRs at any given time, but I only care about the ones my team is making.

Good reminder that having tools that support the way you work makes work a lot easier!

Links from the comments:

https://prfocus.app/

Did some more LLM-assisted coding on a personal project over the weekend

Mon, 08 Dec 2025 08:50:52 -0500

Did some more LLM-assisted coding on a personal project over the weekend. Blew through SO MANY credits working on an old iOS app I never finished, and a website for it. I basically spent my monthly quota in two days, which is wildly unsustainable.

The thing that keeps getting me, though, is how inconsistent and unreliable the outputs are. Sometimes the LLM absolutely nails it. It implements clean, simple code that does the job. In other cases, it totally biffs what I assume will be a simple task, or confidently insists that failing tests are a test framework problem, not an issue with the implementation. (Spoiler: it’s almost never the test framework.)

I keep wanting it to work, and sometimes it does, but the number of times where it doesn’t… that really breaks the immersion in the shared fantasy that this is “intelligent.” And given the cost to get outputs that are sub-par… that’s frustrating.

I recently spiked on what it would take to programmatically test the procedures…

Wed, 03 Dec 2025 10:18:36 -0500

I recently spiked on what it would take to programmatically test the procedures in our documentation.

While that problem domain is super interesting and I will definitely post about it soon, today's takeaway is all about how incremental adoption of documentation platform enhancements can create technical debt that makes it harder to build new things.

We use reStructuredText, and we have three different ways we might structure procedures:

Using a custom procedure directive
Using .yaml "step" files that resolve to a procedure through our build system
Using ordered lists

We also have two ways we might represent mutually exclusive procedure paths:

Using a custom tab directive that often represents different programming languages or interfaces
Using a custom composable-tutorial directive that works similarly, but has a different syntax and presentation

In each of these cases, we have added custom directives to simplify writer workflows but have not gone back and retrofitted the old content to use the new directives. In some cases, for technical reasons, but in other cases, for time-based reasons.

Additionally, we compose these options in inconsistent ways. Sometimes we contain an entire procedure within a mutually-exclusive path choice. And sometimes we use those mutually exclusive procedure path options inside a procedure step. So this represents two different implementations for each of those procedure path implementations.

In total, this represents 12 different variations of procedure implementations that any programmatic tooling must understand.

If we updated our old implementations to adopt the new platform features, that would drop to 2 variations if we only supported the formal procedure directive, or 4 variations if we also want to support ordered lists.

Incremental adoption enables teams to get started quickly with new functionality, but it also creates tech debt that slows down work if the old content is never updated.

In a world where we want AI to help us, having all these variations in implementation also makes it harder for AI to understand our docs structure and effectively complete tasks.

This has been an illuminating project for me in terms of exploring some types of tech debt that we rarely discuss in the documentation world.

I’ve kicked off the annual process of switching the tractor from mower mode to…

Wed, 26 Nov 2025 15:05:17 -0500

I’ve kicked off the annual process of switching the tractor from mower mode to snowblower mode. Over the four winters I’ve owned this, I’ve learned:

I can do it all at once, but it tires me out and puts me in a bad mental state. So I break it down into three separate tasks that I do on different days, which each take 10-30 minutes. Easy.
I’ve done it on really cold days and I’ve learned that things go much more smoothly if I pick a warm day. So I’ve learned to optimize my environment.
I’ve watched a few different videos to learn different techniques and folks from different people. There is rarely one right way to do things, and finding the way that works best for you makes everything click.

These may be life lessons for working with my tractor, but they’re equally applicable to my work life:

Break down tasks into manageable chunks.
Optimize your work environment so you can do your best work.
Try different techniques and learn what works best for you.

Bring on the snow! ❄️

I’ve been exploring how AI can help me with drafting internal documents, like…

Wed, 19 Nov 2025 08:13:08 -0500

I’ve been exploring how AI can help me with drafting internal documents, like project plans.

I tried Gemini in Google Docs and was pretty unhappy with the results. It was clunky to use, difficult to iterate, and there wasn’t a simple way to give it context from elsewhere.

So now I’m doing everything in my IDE with various agents.

I save supporting documents from Google Docs as markdown files. I group them in a directory, and open the directory in my IDE. And then I have a conversation with the agent about what I need. I pose theories and ask it if my supporting docs + academic papers on the web contain data that supports those theories. Or I ask it to analyze data across the different sources. Or I ask it to create queries so I can pull data from various metrics sources I have access to.

This allows me to quickly validate theories (or not!) and easily draft content with supporting data. Then I can refine as needed depending on what kind of doc I’m writing. When I’m done, I paste the markdown from my IDE into a Google Doc using the “Paste as markdown” feature to preserve formatting.

This gives me the flexibility to use my preferred agents and data sources to find the right messages, and then I can wordsmith the result. It has saved me a lot of hours versus manually pouring over hundreds of pages of source material/digging around in metrics myself. I still have to validate the output, because AI, but I think this is my new process for drafting internal docs going forward.

I'm really excited to share what my team has been working on - tooling to…

Thu, 13 Nov 2025 08:35:13 -0500

I'm really excited to share what my team has been working on - tooling to transform how writers test code examples in documentation!

On the left, we have a snippet from one of our old test suites. We used the same tools that developers did to execute code and validate the results. But this required you to be a developer - or at least have near-developer-level-knowledge of testing and testing frameworks. So this tooling was only accessible to a small subset of writers at our org.

On the right, we have a snippet from our new testing paradigm that we're currently rolling out across the org. It abstracts away the testing piece and gives writers a simple way to validate that their code executes successfully and produces the expected results.

They write their code example in a function they can call in a test, create an expected output file that we can show in the docs, and use our comparison utility to validate that the result from executing the code matches the contents of the expected output file. No need to master the individual assert syntax of every testing library in every language we support. No need to write a million individual asserts to validate every value of every object in the output. Just one unified API that works the same across every language.

I'm really proud of the work my team has done here, and will be writing a series of blog posts about what it took to get here. But for now, you can see the whole writer workflow in the new docs we've rolled out for our writing team - link in the comments.

I'm really curious how other orgs handle testing the code examples that they show in their docs. If your org does testing, how do you do it?

Links from the comments:

https://www.mongodb.com/docs/meta/grove/

This week, I'm helping a team of technical writers deliver a new sample app…

Fri, 07 Nov 2025 07:39:56 -0500

This week, I'm helping a team of technical writers deliver a new sample app showing how to use our products with three popular frameworks. I'm slinging around:

Bash
Java
Python
TypeScript
Markdown
YAML

While working on READMEs, repo licenses, .gitignores, GitHub workflows, repo configuration, and a utility/process for copying our sample app from a source monorepo to framework-specific artifact repos to simplify developer usage.

My fellow technical writers have written the app; I'm just out here adding Swagger docs, unit tests, integration tests, doing PR reviews, and setting up infrastructure.

I see posts all the time where technical writers lament seeing so many job postings that require tech writers to have some level of development skill. But the reality is that when we do, we can contribute much deeper and richer learning experiences to help people succeed with our products.

And isn't that the goal?

In personal project news, this weekend my household hit two key milestones in…

Sun, 02 Nov 2025 09:57:05 -0500

In personal project news, this weekend my household hit two key milestones in our project to liberate our smart home from private clouds whose terms of data sharing are no longer acceptable to us:

We removed the Philips Hue bridge from our house while retaining our smart lights
We deleted our home from Apple Home while retaining all of our smart functionality

We have also disabled/removed all listening devices provided by Big Corp; no Siri, Alexa, or Google in our house.

We have lost 0 functionality.

We’re now running everything through Home Assistant. It runs in a Raspberry Pi that’s sitting with our networking equipment in our basement. It’s isolated to its own network, along with the smart hardware, so none of it ever has access to the same network as our computers and phones.

We’ve bought antennas to use our smart light bulbs and thermostats through the Zigbee and ZWave protocols without ever calling out to a server outside of our house. We’ve replaced a couple of smart plugs, two very old Hue bulbs that weren’t Zigbee compatible, and the radio module for our smart door lock with alternate hardware that’s compatible with Home Assistant.

The big question for us was how we get voice functionality. We have gotten spoiled by the ability to talk to the air and set timers or have our smart home respond to voice commands. We bought the Home Assistant Voice Preview Edition to replace Home Pod and Siri on our devices. It does listen, but gives us a lot more control about when it listens. And it is developed solely to serve the privacy-conscious Home Assistant audience. We are the consumers of a product, versus being a product whose data is being monetized in the Big Corp ecosystems.

With the new setup, we get all the same functionality (better, actually) as the old one without giving companies we don’t trust access to our data.

Woohoo, it's live!

Thu, 30 Oct 2025 08:34:04 -0400

Woohoo, it's live! For all my documentarian pals who manually maintain OpenAPI specs, here's a tool you might find useful: OASprey, a package that lets you use the Jest testing framework to validate that real API calls match your API spec.

In this screenshot, we're looking at a Jest test file where we load an OpenAPI spec from our docs, call various endpoints, and assert that the status is 200 and the response we get satisfies the API spec. You can either load the published spec from a URL or the pre-published spec from a local file, depending on your needs.

Each test fails if we get fields or types in the actual response that do not match the fields and types in the API spec. By running the tests regularly, we can validate that the underlying API we've documented still matches the spec. If new fields are added, types are changed, or other breaking changes happen, failing tests will alert us that we need to update the API spec.

This isn't net new - it's a hard fork and modernization of an abandoned utility - but now it's available via npm. Links in comments. Happy testing!

Links from the comments:

I’ve been using my new iOS app this weekend while playing my new-to-me game

Sun, 19 Oct 2025 13:52:39 -0400

I’ve been using my new iOS app this weekend while playing my new-to-me game.

I wanted a few small improvements - custom searchable implementations for Characters to find people who like certain gifts (whatever I happen to have on me) and Recipes to see what recipes I can make with certain ingredients (whatever I happen to have on me).

Pushed the new build to TestFlight and have been using it today while playing and boy oh boy is this a nice feature 😁

I really do love building apps that do exactly what I want them to do in the way I want them to do it. 💖

Sharing: my earlier post introducing the app, with screenshots

I set out to write a script today to figure out how many instances of a given…

Fri, 17 Oct 2025 18:25:34 -0400

I set out to write a script today to figure out how many instances of a given thing we have on a certain docs page.

I paused before I started, thought a minute, and made it a CLI instead.

Now it has 3 commands with various flags that are going to be super useful for evaluating the impact of changes or scoping maintenance work across our docs. And I’m able to reuse some core logic in different ways across the different commands.

Scripts are nice for one-off tasks, but a lot of the problems we solve in docs aren’t one-off tasks.

The next time you’re considering writing a script, maybe make it a CLI instead.

Links from the comments:

https://github.com/mongodb/code-example-tooling/pull/85

Well, crud

Mon, 13 Oct 2025 20:19:02 -0400

Well, crud.

Mere weeks after raving about Augment Code and signing up for a personal subscription because I was so happy with using it at work, they are changing their pricing model.

Under the plan I signed up for, I get “600 user messages” per month. I used about 200 of those during 3 days of my vacation. As a personal user, I could just about get away with 600 if I’m only using it on some nights and the occasional weekend day.

For their new plan, they are switching to a “credits” billing model. I’ve been informed that my messages over the last 7 days have used about 1.5 times the number of credits of the average user on my plan. With the new model, my same monthly sub would translate to about 81 messages.

Down from 600 that I was paying for when I signed up.

81, when I used ~200 in 3 days.

So basically a little over a day of usage will burn through my monthly subscription allotment.

I guess I’m in the market for a new agentic coding assistant for my personal projects!

As the sun sets on my last day of staycation, I am happy to have this little…

Sun, 12 Oct 2025 17:35:52 -0400

As the sun sets on my last day of staycation, I am happy to have this little thing running on my phone. It’s my latest iOS app, designed as a companion app for the cozy video games I like to play. The one shown here is reference info for the game “Story of Seasons: A Wonderful Life.”

Not pictured: the three different Go CLI tools I wrote to help me crawl, explore, and parse data from video game wiki websites to populate the app data. Or the generic, extensible architecture that lets me write plugins for each game, so I can add as many games as I want to this little guy. Or the theme system that lets me style each game’s data uniquely, so the app reflects a given game’s look and feel when you’re viewing the data for that game.

Or the thing I am stupid proud of - the fact that one of the CLI tools writes Swift codable strucs, customized SwiftUI views, and JSON data representing the info I’ve parsed from the wiki.

I’ve made a reference app factory for my cozy game wiki websites. 😁😂🎉

I’ve been working on infrastructure to test the code examples we show in our…

Wed, 01 Oct 2025 08:11:07 -0400

I’ve been working on infrastructure to test the code examples we show in our documentation.

Rolling it out to a working group of early adopters has taught me so much about assumptions, both mine and the folks who are onboarding.

Much like any product, good enablement materials are priceless. Actual docs for this tooling + other learning modalities are essential.

I guess technical writing still has a role to play in today’s world 😁

I have been working at MongoDB for nearly 5 years now

Sat, 27 Sep 2025 10:45:03 -0400

I have been working at MongoDB for nearly 5 years now. That’s also roughly how long I’ve been doing my dev side projects. It’s no coincidence that MongoDB and non-relational databases in general are the default tool I reach for when I need a database for a personal project. I have written and shipped multiple apps that use non-relational databases.

My wife has been a software developer for a lot longer than that. She also uses MongoDB in some of her personal projects, but she comes from a long relational DB background. Her default brain reaches for relational. She keeps trying to convince me to use SQL for things that I am convinced don’t need SQL.

At the same time, I keep catching her ranting about complicated joins and groupings in some of her projects that still use SQL. They’re typically problems I just don’t have in my non-relational world.

My takeaways:

Old habits are hard to break. She can’t quit her SQL even though it’s bad for her 😉
If I can go the rest of my career without ever having to use a relational DB, I will be a happy human 😂

I filed a support ticket with JetBrains recently about a regression

Thu, 25 Sep 2025 07:42:47 -0400

I filed a support ticket with JetBrains recently about a regression. Something that used to work in an older build no longer worked in the most recent build.

They were unable to reproduce my issue. I spent some time putting together a minimum reproducible test case, and in doing so, discovered a setting that solved the issue.

I don’t know whether this was a new setting, or the upgrade process to the latest build somehow lost a setting I had selected in the past. In either event, this setting caused a change in behavior that looked to me, the user, like a bug. A JetBrains support engineer lost time trying to reproduce my issue, and I lost time setting up the test case and also changing my workflows to work around this change in behavior.

Setting defaults matter! If it causes a change in behavior, it probably should have defaulted to the case that preserved the existing behavior. If the setting changed during upgrade, that’s a miss in the upgrade process.

I have put my money where my mouth is

Sat, 20 Sep 2025 18:49:08 -0400

I have put my money where my mouth is.

After trying out a variety of AI agent tools at work this month, I’ve splashed out for a personal subscription to Augment Code for my weekend side-projects.

From my recent experiences, the Augment context management engine really makes a difference in working with AI agents. I’ve used Claude Sonnet 4 with a variety of agent platforms (Copilot, Cursor, Augment, an internal GPT chatbot) and Claude seems to be most effective when paired with Augment’s context management and tool usage.

No, AI agents aren’t perfect. I stub out my functions and try to use descriptive TODOs paired with AI instruction files to give AI the best chance to succeed. Or I write a detailed requirement doc first for larger tasks. Yes, I still have to make tweaks when it’s done. But I can get done in 15 minutes what would take me a few hours to write by hand. I have it end each session by running and adding tests and updating the documentation.

AI speeds up my development workflows. When I have a limited amount of time to work on my fun projects, I can get more done with that time by adding an agent to the mix. We’ll see how it goes, but so far, I’m happy with the new tool!

(Working in a mix of Go and Swift code using Augment as a plugin in JetBrains GoLand. I’m writing Go CLIs to work with data and generate some Swift/SwiftUI code, and then I’ll drop back to Xcode for asset management and distribution for the end-product iOS app I’m writing. Trying to use Xcode as little as possible as I have gotten spoiled by JetBrains.)

Continuing in my AI-assisted coding spelunking, I’ve been trying some different…

Fri, 19 Sep 2025 08:14:59 -0400

Continuing in my AI-assisted coding spelunking, I’ve been trying some different tools this week with surprising (to me) results!

I’ve started experimenting with Augment Code, which offers plugins for VS Code and JetBrains IDEs. It’s similar to Copilot, but in practice, it feels much more sophisticated and robust.

I’ve been using both Augment and Copilot with Claude, so it is theoretically backed by the same AI. But Augment delivers an experience that feels a lot more smooth.

Augment’s context management is like magic. I haven’t yet gotten into a situation where it has had “too much” context and has gotten confused. But with Copilot, I have learned to start fresh with a new agent between each task to limit the context I’m carrying forward.

Augment’s tool usage also seems more sophisticated. It has reached for debugging tools and tricks that I haven’t seen Claude use with Copilot, and it has felt more mature and effective as a result. I have also not been running into Copilot’s rate limits or tool usage limits that stop me and force me to drop out of context until I can resume later. Augment just smoothly continues working until the task is complete.

I don’t know how much of this perception is a more polished UX and how much it is related to how each team has chosen to implement their agentic workflows, but it has been an interesting experience to see such varying results with the same underlying model!

I've been experimenting with various AI tools, and have discovered how precious…

Sun, 14 Sep 2025 14:20:57 -0400

I've been experimenting with various AI tools, and have discovered how precious those premium requests are when it comes to coding-related tasks.

So I wrote a little macOS menu-bar app to help me easily keep track of the number of premium requests I have remaining. The icon color changes when I get low on requests, and if I hit the menu bar item, I can see exactly how many requests I have remaining and when they reset. Clicking on the "remaining" element takes me to the GitHub UI where I can view more about the current state of my premium requests, and could potentially add more.

This is one of those cases where I really love having development chops because then it's trivial to write little tools like these.

Continuing my ai-assisted coding spelunking, I've come up against "premium…

Fri, 12 Sep 2025 11:11:28 -0400

Continuing my ai-assisted coding spelunking, I've come up against "premium request" limitations with my enterprise-sponsored Copilot access. So now I'm branching out to explore other model options and IDE integrations.

JetBrains provides their own AI assistant, Junie, with agentic capabilities. I really like the Junie UX, but I can't get it to actually - work. It keeps failing with execution errors without successfully completing tasks. I put Claude on the most recent task after Junie failed, and Claude also completed the task substantially faster than Junie was working before it failed.

I really want to like Junie, but in my limited testing, it seems not quite ready for real-world usage. (Also, the quotas are ridiculously low. FAR lower than Copilot.)

JetBrains does let you BYO model provider using their AI Assistant integration. I've now started experimenting with local Ollama models running on my machine, which doesn't use up any quota. The models are so far a bit less capable. I iterated with Ollama's gpt-oss for a while and circled around a bug, and then switched to Copilot with GPT 4.1 and got the bug fixed right away. So I think Ollama may be useful for general question/answer stuff on high-level syntax things, but for help debugging, I haven't found the right model yet.

I also wrote a little macOS menu bar app to help me keep tabs on my premium model usage, since apparently this is an issue. I have 31 Claude requests remaining for the month - wish me luck!

Continuing my experiment with agentic coding through Copilot, I noticed the…

Sun, 07 Sep 2025 16:22:27 -0400

Continuing my experiment with agentic coding through Copilot, I noticed the other day that some tasks where Claude had been doing just fine suddenly seemed to be beyond it. And some tell-tale behaviors and quirks started to creep into the chat.

I went digging and found a discussion on the GitHub message boards that GH will switch the model you’re using, even if you have explicitly selected a specific one, to a different model based on - they won’t quite say. Something something “availability.”

Without telling you.

It’s a quiet switch-a-roo under the covers.

Went digging for more info, and found all the stuff about “premium” model usage in the GitHub docs that wasn’t on my company wiki about using our enterprise Copilot access. It didn’t even occur to me that I basically have a quota limiting my “premium” model access which I can use up on tasks that don’t necessarily need it, and then they’ll quietly switch me to a less competent model without saying a word.

Did some exploring about switching my weekend project to pay Anthropic directly for Claude access in my personal projects, and - wow, it’s not cheap, and the quota is LOW and also very vague. From Anthropic’s docs, their mid-tier plan provides “45 uses per 5 hours for most low-intensity, low-compute tasks” - which most of my agentic stuff is not.

Went looking at JetBrains stuff and the quota is even lower and more vague.

So now I’m using Ollama with a few different local models through the JetBrains “AI Assistant” integration, and have basically dropped agentic workflows. I’m back to writing code by hand, and using AI as an occasional syntax reference instead of dropping out of my IDE to a browser to look something up.

While I was at it, I rewrote a bunch of stuff that the AI wrote last weekend to be much cleaner, simpler, and use better patterns. Apparently AI doesn’t know how to make code simple and DRY.

This may be a short-lived agentic coding experiment. I’ll try a bit more in a work project I’ve got going, but I might be through with agents for now in my personal projects.

I've been a slow AI adopter because my early experiences with it produced…

Tue, 02 Sep 2025 07:11:54 -0400

I've been a slow AI adopter because my early experiences with it produced low-quality output. I've finally started to experiment with agents. My immediate thought was "wow, now I'm moving so fast!" But - was I doing it the right way? Was the output still low-quality?

So I gave myself a low-stakes personal coding project to work on over the long weekend to dive deeper.

The result: I have code. A lot of code. And some tests. I only wrote about 5% of the code myself, and none of the tests.

There were a lot of bugs. And a lot of time spent wrangling the agent to "make this change, not that" and undo things it kept trying to redo in a "wrong" way.

I got to iterate fast, in places. And I got very bogged down in other places.

Sometimes, it almost felt magical. I got to describe something in plain language, the agent went off and wrote code, and then I saw what I described come to life. I didn't have to think about all of the implementation details.

And then it didn't work the way I wanted it to because I didn't think about all of the implementation details.

I am confident that I got a lot more done than I would have over the same period of writing everything myself. But it's clear to me that I need more practice with agents to get the results I want, if that's even possible.

Guess my personal coding project will continue!

Hah, I take some of it back

Thu, 28 Aug 2025 07:58:18 -0400

Hah, I take some of it back. 😂

I posted the other day about how much better Claude was than GPT 4.1 at some coding-related tasks in agentic mode.

Later, I asked Claude to break up a couple of long files that it wrote into smaller logical units to make it easier for my team to review and maintain.

It created a very reasonable implementation plan. But then it utterly failed in execution, repeatedly.

After giving it 3 chances using different prompts spanning more than an hour (I was working on different things that required a human), I took over and did it myself. It took me 5 minutes.

Can write reasonable code to accomplish a task - check.

Can refactor that code to improve readability and maintainability - apparently not 😂

I’m convinced - when you’re leveraging AI in your workflows, model matters

Tue, 26 Aug 2025 20:39:31 -0400

I’m convinced - when you’re leveraging AI in your workflows, model matters.

I spent hours going around in circles trying to get Copilot with GPT 4.1 to implement something based on my requirements. It kept stumbling on logic issues and making changes, then changing things back, without ever solving the implementation issues.

Eventually, I continued using Copilot, but switched the model to Claude Sonnet 4, and had it solved, completely refactored, thoroughly tested, and documented in under an hour.

Had Claude write a spec so we could implement similar functionality in another language. Got a working, tested implementation in a second language in 20 minutes.

In agentic mode, Claude is eager and aggressive, touching files and making changes even when I ask for suggestions instead of edits. But it’s also effective and fast, and the code it produces is relatively logical and easy to follow.

GPT 4.1 is deferential and follows the rules I set for it, but it’s also slow and bumbling at code-related tasks. The code it produces is overly complicated and difficult to follow.

Both have problems with misplaced brackets and structural syntax issues in larger files. Claude has been faster and more effective at fixing those issues when they happen. Claude is also better at refactoring to break things down and make complex code more maintainable without losing functionality.

This one is for all of my tech writing friends who have ever had to hand-write…

Mon, 18 Aug 2025 22:16:54 -0400

This one is for all of my tech writing friends who have ever had to hand-write and maintain OpenAPI spec manually...

I've forked and updated an abandoned library that can test OpenAPI endpoints trivially easily.

You load the OpenAPI spec - either from a local file, or from a remote URL, such as a live docs page.

Then you call a live endpoint, and use test framework assertions to validate that you get the expected status code and that the API response matches the schema that your OpenAPI spec has defined for that endpoint/status.

All with a few lines of code.

This is definitely going into my toolkit!

In the last few weeks, I've been rolling out our new code example test…

Mon, 04 Aug 2025 22:06:09 -0400

In the last few weeks, I've been rolling out our new code example test infrastructure for C#, Java, JavaScript, and Python. This week, I'm adding support for a shell tool. Next week, Go.

But all the tooling in the world does no good if people don't know how to use it.

I'm pairing this rollout with:

High-level process documentation on our company wiki
Implementation-specific READMEs with a consistent topic coverage for every programming language and product
Workshops for writers who will be contributing net new code examples using our test infrastructure in upcoming projects
Setting up a working group to onboard early adopters from every team across the docs org
Providing a NotebookLM loaded with all of this source content so people can easily get answers without having to pour over all of the specifics

I will make updates to tooling and process based on these first few real-world projects and the feedback of our early adopters. And then I will socialize the rollout more broadly and seek to drive wider adoption.

I am super excited to bring this tooling to the wider org, and want to provide the training and resources to make it easy to adopt. 🎉 🙏

Technical writers - how do you roll out new tools and processes? Did I miss anything?

If you are a technical writer who documents software, learning to use your…

Fri, 01 Aug 2025 07:55:52 -0400

If you are a technical writer who documents software, learning to use your version control system's APIs is a force multiplier.

It's easy for Jira or other tracking processes to fall behind reality. When you document software, the code is the source of truth. So don't watch Jira - watch the code!

I learned GitHub's APIs to write PR Focus, an app that let me keep track of engineering feature PRs. Since I work in a docs-as-code workflow, it also let me easily stay on top of my work.

Since then, I've been writing little utilities that use GitHub's APIs.

I've got a script that gets traffic metrics from some public-facing code example repos we maintain. I write the metrics to a database which populates a dashboard for stakeholders. This lets us make data-driven decisions about developer engagement with code examples and how much we want to invest in maintenance.

This week, I added a script to check the release versions of the products we document and compare them against the versions we use in our test infrastructure. It automatically creates tickets for my team to update test infrastructure when we fall behind a release version.

Learn the APIs that can give you information about the state of code that matters to you. Code is the source of truth in software documentation - not Jira.

Reminder for all the technical writers and documentarians out there… your job…

Thu, 01 May 2025 11:23:35 -0400

Reminder for all the technical writers and documentarians out there… your job has two components:

Doing the work you do.
Communicating about the work you do to other teams, leadership, the broader industry, etc.

Don’t neglect the communication! Your org needs to understand your work, the value you bring, and how it fits into the broader organization’s objectives.

Just finished writing some tooling to programmatically extract our hard-coded…

Wed, 30 Apr 2025 12:56:11 -0400

Just finished writing some tooling to programmatically extract our hard-coded inline code examples out to separate files which can be included in the docs.

Code examples that are hard-coded inline in your docs may have been tested at the time they were added, but the moment you hard-code them inline, they become decoupled from the product and untestable going forward.

You can’t test them with new SDK or API versions.
You miss out on basic compile testing for valid syntax.
You can’t use linters to standardize the formatting of your code examples.

If you value accuracy, consistency, and maintainability, don’t hard-code your code examples inline in your docs!

Links from the comments:

https://github.com/cbush/docdoctor/pull/13

Continuing to think about code examples in documentation, and I'm starting to…

Tue, 17 Sep 2024 09:14:40 -0400

Continuing to think about code examples in documentation, and I'm starting to ideate around some core concepts, or "Pillars" of code examples:

Coverage: How complete is the code example coverage within the documentation? Does every API have the right quantity of code examples, demonstrating usage at the right levels of abstraction? Do code examples show not just the API itself, but how to get/form the arguments for the API, and how to work with whatever the API returns?
Maintenance: Are the code examples tested? Are tests run with every version update/code example change? Do tickets get generated to update code examples when APIs change? Is there a governance policy for archiving code examples for old versions?
Discoverability: Can developers find your code examples? Are they available not just in your documentation, but in GitHub and/or LLMs? Do third-party sources have information that leads developers back to your code examples - i.e. package manager release notes, READMEs off your website, etc.?

Curious for your thoughts, #TechnicalWriters and #Developers - do these pillars resonate with you? Are there things I'm missing, or things you think are particularly important?

I got a lot of interesting and thoughtful replies to my post yesterday about…

Thu, 12 Sep 2024 09:13:14 -0400

I got a lot of interesting and thoughtful replies to my post yesterday about code examples in docs, but I've got a hot take on one of the themes that emerged... that code examples should vary depending on the intended audience. (Skill/experience level, etc.)

That's a common convention in technical writing, but I have never seen this done effectively with code examples.

I have never seen a docs set that allowed me to specify my skill level - i.e. experienced developer who is new to this tech versus new developer. I have also never seen a docs set that effectively tailored examples for different experience levels.

I have seen docs marked "Beginner," "Intermediate," "Advanced." And I've seen from experience that docs writers are bad at assessing what should be in each skill level when it's generic like this, and developers are bad at self-selecting their skill level.

So - I think this theory that code examples should be different for different audiences doesn't hold up to any real-world docs sets I've seen.

Do you have a favorite docs set that you think actually implements this?

(I also have thoughts about the maintenance burden this requires. I made a proposal in my org earlier this year to single-source different levels of code examples from a single tested example, but haven't had a chance to go beyond proposal with this yet. I think it would be very easy to create a major maintenance burden if this isn't single-sourced from a tested example set.)

I’ve been thinking a lot lately about code examples in documentation

Wed, 11 Sep 2024 13:00:29 -0400

I’ve been thinking a lot lately about code examples in documentation.

What makes a good code example in a docs set?

How much should we break stuff down? Do you want code examples that are in separate files so they’re easy to reuse, or one big file so you can run it easily?

How realistic should a code example be - should it show error handling?

If you need to run code in incremental steps, should those be in separate examples, or should we give instructions about where to paste it into an existing example, or should it be commented out but present in the original example?

Does a single line count as a code example?

It’s amazing how few industry best practices exist around code examples, when they are such an important component in docs that are meant to teach developers how to use your APIs.

The next PR Focus release is almost ready, and it brings a focus on individual…

Thu, 29 Aug 2024 07:52:05 -0400

The next PR Focus release is almost ready, and it brings a focus on individual contributor workflows! There is a new "Principal PRs" dashboard that shows only:

My PRs
Assigned PRs
Reviewing PRs

For folks who don't want to watch or ignore other pull request activity in a repository, there is a setting to make this the default view in PR Focus.

And! The extra real estate for the "My PRs" list means there's space to surface more actionable information in the pull request summary. So this release adds badges for "Approved" and "Changes Requested" directly to the PR summary, meaning you don't have to click into the details and can quickly scan for actionable updates.

This release is almost ready to go - there's one more small feature I'd like to sneak in. Hoping to have it ready over the weekend!

Naming things is hard

Wed, 28 Aug 2024 08:29:07 -0400

Naming things is hard.

I’m adding a new dashboard to PR Focus where people can view only the pull requests they’re involved in. This consists of two, or potentially three, lists of PRs:

My PRs (PRs where the user is the PR author)
Assignee PRs
Reviewing PRs

“Mine” doesn’t work as a UI label, because most people would expect that to be just “My PRs” - not the assignee and reviewing columns.

I was thinking “Contributor”, but spousey argued you’re not really a “contributor” if you’re reviewing a PR - especially if you have only been tagged and haven’t reviewed it yet.

Spousey started suggesting acronyms - “CAR” and “RAM”, but I have SO MUCH resistance to an acronym as a UI label. I’m sure there are times where it’s the best option, but this doesn’t feel like one of them.

I have tentatively landed on “Principal” but I don’t love it.

Someone suggested “Active”, as a counterpoint to some of the other UI labels (“Inactive” and “Archived”), but there is another dashboard where you can watch PRs where you’re not a contributor, and those PRs could also be active. So that doesn’t work in the larger context of the app’s functionality.

Words are important. Getting the right word can sometimes be hard.

PSA

Mon, 26 Aug 2024 12:42:43 -0400

PSA: If you are storing static information in Discord, or requiring folks to join a Discord server to get information about your product, you’re doing it wrong.

Discord is a chat app.

If you have static information to convey, that does not belong in a chat app.

It should be a website.

Doubly so if the static information is documentation.

There was an interesting conversation in Write the Docs about a guided code…

Tue, 20 Aug 2024 13:29:59 -0400

There was an interesting conversation in Write the Docs about a guided code experience where explanation is presented side-by-side with code examples. As you scroll through the explanation, the code example on the right changes to reflect the next step, where the relevant content is highlighted.

Apple has my favorite implementation of this guided code experience in their developer tutorials - here's an example: https://developer.apple.com/tutorials/swiftui-concepts/scaling-views-to-complement-text

Curious how many #TechnicalWriters are doing something like this with their docs? Do you have thoughts on this way of presenting code and content? Maintenance considerations?

My team has stepped tutorials with code examples, but the presentation is very different - I really like this side-by-side component.

PR Focus v1.1.0 is live, bringing you two new requested features and some new…

Mon, 19 Aug 2024 13:35:24 -0400

PR Focus v1.1.0 is live, bringing you two new requested features and some new accessibility settings 🎉

Tag PRs. Create custom tags in PR Focus and apply them to your PRs. Track important activity across feature development, bug fixes, or a specific project - even across repos. Filter by tag and date range in the new Tagged PRs dashboard to report on activity to key stakeholders.
Automatically Watch, Ignore, or Tag PRs with Filters. Create custom filters based on PR author username, title, description, or repository. With user-defined filters, PR Focus can automatically ignore Snyk dependency PRs, for example, or automatically watch or Tag PRs following a specific naming convention.
Accessibility settings: display text instead of glyphs for PR status and review status.

For more details, including links to the docs for these new features, check out the announcement: https://prfocus.app/news/2024/08/12/introducing-tags-and-filtering-in-pr-focus/

Another weekend is here, so it's time to work on my app - i.e

Sat, 17 Aug 2024 12:07:58 -0400

Another weekend is here, so it's time to work on my app - i.e. PR Focus!

My reach is very limited, so I'm doing some marketing and sponsorships to let more people know about my helpful little app. Since I'm spending money on it, I want to know how it's performing.

But - I refuse to use Google Analytics, or any tracking software that sells user data. (I also don't use Google - I pay for a private search engine that doesn't track me - and I bounce from sites where I can't opt out of cookies. But that's a story for another day!)

You know what doesn't track you or sell your data? A C library written in the 90s that aggregates data from web server logs.

I just spent 2 hours building out a spreadsheet to aggregate the data I want to track across different sources (website, Apple App Store Connect). I can pull info from my server log reports to populate the website data in my spreadsheet, and pull data from App Store Connect to track activity and sales.

Is it perfect attribution? Nope.

But it respects the privacy of my users.

Be the change you want to see.

Now that PR Focus 1.0 is live, I'm free to start working on new features again!

Mon, 12 Aug 2024 09:12:51 -0400

Now that PR Focus 1.0 is live, I'm free to start working on new features again!

So here's a sneak peek at what's coming in the next release...

The ability to tag PRs in PR Focus.
- Easily track work related to a specific project or release, even across repos.
- View PRs with a given tag, and optionally within a specific date range.
The ability to create filters in PR Focus.
- Automatically Watch, Ignore, or Tag incoming PRs that meet criteria you define.
- Have Bug/Feature naming conventions? Tag all the PRs that come in with your title criteria with a "Bug" or "Feature" tag so you can easily keep track of important work.
- Want to always ignore a certain type of PR? Automatically Ignore PRs you don't care about, such as dependency update PRs from Snyk.

These new features are all in, working, and tested - I'm just cleaning up UI elements preparing docs! Expect to see these in an update within the next week or two. 🎉

My macOS app, PR Focus, is now live on the Mac App Store!

Mon, 05 Aug 2024 07:58:36 -0400

My macOS app, PR Focus, is now live on the Mac App Store! 🎉

I really appreciate all the feedback I've gotten from the beta test group. Now that 1.0 is launched, I'm looking forward to digging into some of the new feature requests I've gotten!

(I may have dreamed about code last night for one of those new features... sleep can't slow me down!)

If you have ever wanted to know the status of a pull request - or a bunch of pull requests - without having to go to GitHub to check on them, give PR Focus a try!

https://apps.apple.com/us/app/prfocus/id6449602269

I’m prepping a “Tech Writing 101” talk for our interns about working with…

Mon, 22 Jul 2024 13:42:07 -0400

I’m prepping a “Tech Writing 101” talk for our interns about working with external stakeholders.

For the purpose of this talk, I’m defining “external stakeholders” as members of the org but outside of the immediate documentation team - I.e. product managers, engineers, etc.

Curious if anyone has any good tips/process/strategy recommendations that might be valuable for interns to learn. I’m riding the balance of “what skills does someone at that point in their career need to develop” with “a glimpse of what it might look like as they progress in their career.”

Thoughts?

It has been an awesome first week of public beta for my upcoming app, PR Focus!

Fri, 19 Jul 2024 09:09:20 -0400

It has been an awesome first week of public beta for my upcoming app, PR Focus!

I've gotten - and fixed - 4 bug reports. I'm testing a new private build today, and assuming it all looks good, I'll push out an updated build this weekend.

I've also gotten some fantastic new feature requests that I've added to the post-launch roadmap: the ability to tag and filter pull requests!

Tagging will enable you to create your own arbitrary groupings in PR Focus without having to expose the tags via GitHub. So you can tag pull requests across different repos as related to a specific feature, for example, and see them all in one place.

Filters will allow you to define custom rules to automatically Watch, Ignore, or Tag incoming pull requests. So you can automatically Ignore Snyk dependency update PRs, for example, or automatically apply specific tags for PRs matching keywords you define.

Thanks for the awesome ideas, beta testers! These new features sound great.

I've still got a few spots open in the public beta - I'd love to hear from you!

https://testflight.apple.com/join/PmdjrF6U

After more than 2 years of work (April 6, 2022!), my macOS app, PR Focus, is…

Mon, 15 Jul 2024 22:26:11 -0400

After more than 2 years of work (April 6, 2022!), my macOS app, PR Focus, is finally ready for public beta!

If you are a #TechnicalWriter who works with engineers who occasionally forget to mention when something needs a documentation update, or...

If you are a #Developer or #DocsAsCode technical writer who makes or reviews PRs, or is assigned work in GitHub...

You might find PR Focus a useful tool to help you keep track of PRs across multiple repositories - all in a single dashboard.

I've just finished adding more info and some App Preview videos to the website: https://prfocus.app/

I have been using it daily at work for over a year in its current incarnation, have had a group of colleagues using it to provide feedback, and am finally satisfied enough with the level of fit and finish to share it with others. I have gotten so much value from it, it has kept me learning and working through the queue of bugs and grown to the point that it might be quite useful to others.

If you're interested in joining the public beta, you can join the TestFlight beta group here: https://testflight.apple.com/join/PmdjrF6U

Continuing my series about testing the code examples in documentation, I've…

Sun, 11 Feb 2024 23:30:34 -0500

Continuing my series about testing the code examples in documentation, I've just put up a post about what to test in docs code examples.

Spoiler alert: it might be both more and less than you think!

Curious to hear how this resonates with other #TechnicalWriters - particularly SDK and API #Documentation teams.

We are getting into the holiday season, and it seems like the velocity of…

Tue, 05 Dec 2023 21:24:25 -0500

We are getting into the holiday season, and it seems like the velocity of feature delivery slows down this time of year. How do you like to use this slower time of year? Are there proactive projects that you tackle? Maintenance work you prioritize? Planning so you can hit the ground running in the new year?

My team is working on a couple of projects that require cross-team alignment, and we’re also planning to swarm on something that hasn’t gotten much attention in the second half of this year. I am also trying to squeeze in some maintenance stuff. Somehow I manage to fill up even the slow times! Curious how my fellow #TechnicalWriters and #Documentarians use this time of year.

For the past few weeks, I've been deep diving into my fall hackathon project

Wed, 15 Nov 2023 08:38:20 -0500

For the past few weeks, I've been deep diving into my fall hackathon project. Today, I'm breaking down how I used the data I ingested from Google Sheets to create awesome MongoDB Charts to visualize documentation metadata for my team.

If you'd like to know what charts I built, how I set them up, and what questions I'm hoping they can answer for my team, check it out!

Are you a technical writer who has something similar for your team? I'd love to hear what data you track, how you use it, how you visualize it, and how you share it.

Last week, I was updating a doc and realized we have two very similar-sounding…

Mon, 13 Nov 2023 17:28:32 -0500

Last week, I was updating a doc and realized we have two very similar-sounding APIs:

writeAsync
asyncWrite

One existed before Swift introduced its async/await syntax, and used callbacks.

The other was added to support async/await syntax.

Someone noticed this in the docs and was confused about which one to use. Which made me realize I need to do a better job disambiguating these in the docs.
I bolted on a lot of async/await stuff and it may be time for a holistic revisit of async functionality.

This is a good reminder of WHY you have to actively maintain docs. It’s very easy to add or update docs in one place, and miss resulting changes in other places.

I haven’t found a better tool for this than regular audits and gap analysis. But to do that effectively requires someone with good subject matter expertise who can spot things that have changed and need updates.

Tech writers, do you have good process around this? What is it?

Last week, I posted about how I used our fall hackathon at MongoDB to get…

Wed, 08 Nov 2023 09:18:31 -0500

Last week, I posted about how I used our fall hackathon at MongoDB to get Google Analytics data out of a spreadsheet and into MongoDB Atlas.

This week, I'm looking at how I transformed documentation metadata in Atlas to make it easy for us to get the insights we want. I look at what questions we want to ask, and what data we need to support those questions. And then dive into some practical aggregation pipelines to set up the data!

We had our fall hackathon at MongoDB last week!

Thu, 02 Nov 2023 08:37:25 -0400

We had our fall hackathon at MongoDB last week! I decided to use the time to get Google Analytics data for the documentation that my team writes out of an unwieldy spreadsheet and into MongoDB Atlas, where I can more easily analyze the data and build useful Charts visualizing the data for my team.

In Part 1 of my 3-part series about my hackathon project, I look at how to get data out of Google Sheets and into MongoDB Atlas using Google App Scripts, a Data API HTTPS Endpoint, and an Atlas Function.

I recently wrote about why you should test the code examples in your documentation

Thu, 26 Oct 2023 23:29:12 -0400

I recently wrote about why you should test the code examples in your documentation. That led to some interesting conversations - notably about who should be writing the code examples in your documentation.

After talking with other technical writers and engineers, I jotted down some of the benefits of having the documentation team writing the code examples. I'm sure I've missed some!

Do you have opinions about whether #TechnicalWriters or #Developers should be writing the example code in your docs? Tell me about them - I'd love to hear it!

Today I was musing about how we as #TechnicalWriters know when to update documentation

Wed, 18 Oct 2023 16:43:58 -0400

Today I was musing about how we as #TechnicalWriters know when to update documentation. Are there processes or strategies you use to find out about changes to the product? Do you rely on product or engineering to tell you about upcoming changes? Are you embedded on teams where you're involved in planning and can decide for yourself when to update docs?

I had a few thoughts based on how I do things - including a tool I wrote to help - but I'm really curious how other #Documentarians approach this challenge.

Just a sneak peek of something I've been working on

Thu, 31 Aug 2023 11:31:03 -0400

Just a sneak peek of something I've been working on...

Are you a #TechnicalWriter who works with engineers who occasionally forget to mention when something needs a documentation update?

Are you a #Developer or #DocsAsCode technical writer who makes or reviews PRs, or is assigned work in GitHub?

PR Focus is a macOS app that lets you watch GitHub repositories, see new and updated PRs in those repositories, and "Watch" or "Ignore" pull requests depending on whether they may need some action from you. PRs automatically show up in your "Reviewing" or "Assigned" columns if you're a requested reviewer or assignee, or if you become a reviewer. When the PR is merged, you can decide how long it should continue to show up in the dashboard before it moves to "Archived" or you can right-click to dismiss it from your dashboard.

Gone are the days when you had to check on multiple different repositories to see what's new and updated. No more losing track of outstanding PRs that require some action from you. Just one awesome app to help you stay on top of PRs you care about.

My team is shaking things up and helping out with some wider docs projects…

Thu, 27 Apr 2023 21:42:37 -0400

My team is shaking things up and helping out with some wider docs projects, which gives me a chance to help out with the Realm Kotlin SDK docs for a bit.

This is my first time really touching Kotlin, and I probably would have been intimidated to try a few languages ago. But after branching out from Swift to help out with C++, Flutter, and now Kotlin docs, plus building tools in TypeScript and Python, I’m not intimidated to touch new languages anymore. And I’ve learned that if you know a set of APIs really well, it’s not that difficult to figure out how to use them in another language.

Still loving a job that constantly lets me learn new things and grow my skills. Grateful all the time for the recruiter who reached out to me in 2020 about a job that united my tech writing background with a chance to grow development skills.

This week is hubby’s first week at a new job after being laid off at the…

Thu, 13 Apr 2023 08:53:00 -0400

This week is hubby’s first week at a new job after being laid off at the beginning of November. He’s been a developer for over 20 years and this is the longest it has taken him to find a job. Typically, when he changes jobs, it take less than a month.

It’s tough out there right now, folks.

Thinking of everyone who is looking right now. You’re not alone.

When you write for a living, your hands are your livelihood

Thu, 30 Mar 2023 08:35:38 -0400

When you write for a living, your hands are your livelihood. I wrecked mine by typing thousands of words a day on a cramped laptop keyboard in my 20s. I switched to the Kinesis Advantage keyboard to reduce hand pain and prolong my working life, and eventually to the Advantage 2. But the fixed width still isn’t ideal from an ergo perspective, and the heavy case and wire doesn’t really fit with my modern minimalist desk setup.

Enter the Glove80, my new split bluetooth keyboard that arrived yesterday. I immediately had to remap a bunch of keys because I’m a nerd who uses a very customized key layout. But Glove80 made it easy, and even uses the same size keycaps for all keys so I can move them around to actually match my layout. First time in many years the labels on my keys actually match the layout.

Pretty psyched for this improvement! I suspect the Kinesis keyboard will be going away for good this weekend.

One of MongoDB's core values is #buildtogether

Mon, 23 Jan 2023 09:49:15 -0500

One of MongoDB's core values is #buildtogether . This is one of my favorites, because the end result is always something better than an individual could achieve alone.

As an example, I led a Docs Maintenance Working Group a while ago that attempted to systematically identify maintenance needs so we can proactively address them. One of the things we came up with was "remove unused files from our docs repositories."

My awesome lead @cbush not only extended a tool that he wrote to work with our docs repositories to identify files that aren't used in our docs - he also set up a GitHub workflow to run this tool on every PR. So any time we make changes that result in unused files, we get a reminder to remove those files from the repo. This is above and beyond the original ask of "remove unused files."

Also, this has had the follow-on effect of causing me to prune our code example unit tests to remove unused code examples and unused tests, reducing the number of tests to maintain and making the unit test suite faster to run.

This is why #buildtogether is so powerful. One person has an idea. Another person adds to it and makes it better. Follow-on effects amplify the impact.

It's so great to work in an org where we live our values every day, and those values have a real impact on the work we do.

Was reminded today that it is my two-year anniversary at MongoDB!

Tue, 17 Jan 2023 18:13:51 -0500

Was reminded today that it is my two-year anniversary at MongoDB! How do I feel after two years in Developer Education?

I love my job. I love going to work every day, having the opportunity to learn new things constantly, and hopefully make life better for the developers who use Realm Database and MongoDB App Services. I have loved using these things myself in personal projects to better understand the folks we write code examples and documentation for - and I also just genuinely think they're great tools and like using them.

I love working with smart people who are generous with their time and knowledge. I love feeling supported and challenged by my team and my work. This is such a happy role for me that unites my interest in app development and my background in writing.

I am very grateful to be where I am and looking forward to year three!

My #ios app’s info page had a link to the Twitter account I set up for it

Fri, 16 Dec 2022 08:45:57 -0500

My #ios app’s info page had a link to the Twitter account I set up for it. Given everything that is going on over there these days, I wanted to switch that to a Mastodon instance that hubby set up for our side projects.

Haven’t touched the code in 8 months. Went to archive and there were missing symbols. “Aha! I remember the #realm #swift team had a version whose release notes mentioned addressing this.” Update the version to most recent, and everything just works again.

Bonus: I wrote a zillion tests for the app back when I was actively developing it, and after updating the version, the tests all still passed!

I’ve been getting into some small semi-abandoned packages lately for some niche stuff in the new apps I’m working on, and it’s such a night-and-day difference using a project that’s actually maintained by thoughtful devs. ❤️

Hubby had an idea for an app that he shared with me on Friday night

Mon, 12 Dec 2022 22:59:14 -0500

Hubby had an idea for an app that he shared with me on Friday night. I knew we could achieve it with a minimal amount of work using MongoDB’s Atlas Functions, Device Sync, and Twilio. We started working on it on Saturday morning, and by Sunday night we had a working app that could receive text messages via Twilio, insert them into Atlas, and sync them with a SwiftUI #iOS client using Device Sync. I put up the app on TestFlight under 48 hours after we started working on it.

This right here is why #MongoDB is an amazing platform for #developers to build on. It gives us fantastic tools to build fast and takes care of so much hard stuff so we can just build cool things. Psyched to take this from TestFlight beta to published app.

Will I get it done in 2022? Let’s find out!

Really enjoying learning C++ to help document the Realm C++ SDK our engineers…

Thu, 01 Dec 2022 23:08:46 -0500

Really enjoying learning C++ to help document the Realm C++ SDK our engineers are rolling out. I dabbled in C a little bit when I was going through some Computer Science fundamental courses and it’s fun to dip my toes in #cpp. And of course, it’s great to have a lead like @cbush who knows the language well and is happy to explain things and help me over some newb debugging hurdles.

I’m so happy to have a job I enjoy this much; one that lets me learn new things all the time and work with smart and supportive teammates who strive to help one another be successful. #MongoDB talks about how it wants to be an inflection point for people’s careers, and it has certainly been one for me. So grateful to the recruiter who reached out to me in late 2020 about joining the Developer Education team, and to the lead who advocated for having me on the team even though I didn’t have a traditional development background. This place is great and my job is awesome 😁

In my role on the developer education team at MongoDB, I wrote and maintain a…

Tue, 08 Nov 2022 13:31:20 -0500

In my role on the developer education team at MongoDB, I wrote and maintain a SwiftUI #iOS app - a basic task tracker - that serves as a template app to build on to get started with Realm Database and Device Sync.

I regularly want a local SwiftUI Realm app to test new features and functionality, as well as PoC small app ideas, so I've made a non-Sync version of this app template. It's intentionally minimal in styling, model, and functionality to make it easy for you to adapt and build with it.

If you might find something like this useful, check out my little summary on DEV Community with some screenshots & info: https://dev.to/dacharyc/realm-swiftui-template-app-5hg8

Or if you want to take a look at the GitHub repo directly, it's here: https://github.com/dacharyc/realm-swiftui-local-client

For now, I can easily branch from here to spin up new versions of the app to test out different features and PoCs. But maybe someday soon I'll spend the extra time to make this a template in Xcode.

This was a rough week for people in tech

Fri, 04 Nov 2022 22:11:12 -0400

This was a rough week for people in tech. One of my best friends lost his job this morning. My husband lost his job earlier this week. Thousands of other people are in the same position right now. The timing going into the holiday season is pretty awful.

My thoughts are with everyone who finds themselves suddenly unemployed right now. I hope you all land somewhere that values you more than the places you just departed.

I just realized it's been 5 years ago this month since we moved out of Boston…

Wed, 03 Aug 2022 08:55:47 -0400

I just realized it's been 5 years ago this month since we moved out of Boston to a small town in Vermont.

Boston was home to a lot of great places to work. We were definitely concerned about the difficulty of changing jobs once we went fully remote, as there were a lot fewer places that were completely remote or hybrid at the time. But we basically spent every nice weekend leaving the city to go camping or hiking, and decided that taking the risk to improve our quality of life was worth it.

Fast forward to today where things are quite different. I have changed jobs twice since then; once to a fully-remote company, and then to a hybrid company. Both times were for roles that I thought would be a better fit for me, and I am so happy where I am today.

When I finish work for the day, I can step out my door and see our small pond or the adjacent wetlands, and the Green Mountains that surround us. We walk the dogs several miles daily on our property in wide, meandering circles where we regularly encounter bunnies, all kinds of birds, deer, and the occasional beaver or bear. If I have a stressful meeting or a sleepy afternoon, I can step out onto our back deck and listen to the wind rustling the trees and birds singing for a few moments of relaxation.

No traffic noises, city smells, neighbors right on top of you arguing loudly over dinner, or obnoxious weekend parties across the street.

When I see people debating remote work, I think about all the people like me who have moved out of cities to improve their quality of life. I think about the fact that what we spent on real estate here would buy us a fixer-upper studio apartment in our old neighborhood.

The ability to work remotely has afforded me such a quality of life improvement. And when I am in my office working, I am relaxed, refreshed, and giving it 100%. I'm not distracted by an open floor plan or people dropping by my desk to ask me a question.

I sincerely hope we don't lose the gains in remote work that we've made during the pandemic. I think it's only good for businesses and employees alike.

We just finished a week-long hackathon at MongoDB where employees are…

Sat, 23 Jul 2022 12:37:17 -0400

We just finished a week-long hackathon at MongoDB where employees are encouraged to cancel meetings and put aside regular work to focus on hackathon projects. For this hackathon, I led a team that implemented a GitHub Workflow to rate the readability of files we touch in documentation PRs, and report those scores as comments on the GitHub PRs.

As the hackathon closes, we have a working demo! This is very close to being able to use it in our documentation repositories as-is to give writers info about how readable our docs pages are. I need to do a little more tweaking of the script that traverses rST nodes and outputs plain text, in order to improve the accuracy of the scores, but it is an awesome tool to have for our documentation teams.

In the future, I'm hoping to add more info, like a delta in the score between main and the PR branch - i.e. does this PR improve or decrease the readability score - and apply additional heuristics so we can get a more well-rounded view of a page's readability.

I love being a part of an organization that takes time out of regular work to encourage employees to work on interesting or helpful projects, and being part of a team that can build tools like this that can potentially make a positive impact across our entire docs organization.

What is it like to be part of an awesome team at work?

Mon, 23 May 2022 18:43:02 -0400

What is it like to be part of an awesome team at work?

My teammate @bpmutter gave a talk at the Write the Docs conference today about the value of unit testing code examples in docs, and how to do it.

Ahead of this talk, our team collaborated on a bunch of improvements to our tooling around this to prepare it for a v1 release.

Last Friday, we cut a v1.0 release of Bluehawk, our markup tool for extracting code examples and creating checkpointed tutorials. It was a team effort, and I’m super proud of how we came together to prep this release in support of Ben’s talk.

(And of course, awesome work on the talk, Ben!)

If you’re someone who needs to provide code examples in documentation, this tool might be useful to you:

https://github.com/mongodb-university/Bluehawk

Ah, yes, the new app developer pitfall

Tue, 26 Apr 2022 08:59:21 -0400

Ah, yes, the new app developer pitfall: I have reached peak "Everything is better as an app!"

Every quarter, I have a service crawl our docs site and generate a readability report. Unfortunately, due to limitations with the service, this report is a CSV that contains ~35k rows and ~77 columns. If I try opening this in Excel or Numbers, it majorly lags my computer and I can't do anything like sorting or bulk operations - it just freezes. So I need to do some pre-processing to make this CSV easier to work with.

I started looking at some command-line tools to work with CSVs, but the documentation was poor around the filtering options and I couldn't get the result I wanted. So new-app-developer me decides to grab a Swift CSV library and create an app to deal with this. Now I've got a macOS app that reads the CSV, ignores the columns I don't want, applies some filtering to the rows, and spits out a new CSV with just the data I want. The UI is a single button "Get report."

Eventually I'll beef it up so other teams at work can use it, but for now, I'll stick with my silly button in an app that doesn't even need to be an app - but I made it one anyway because I can and it makes my work more fun.

I had so much fun developing Shattered Ring that I’ve dived into developing a macOS app

Mon, 18 Apr 2022 07:53:01 -0400

I had so much fun developing Shattered Ring that I’ve dived into developing a macOS app. This one uses Realm Sync, as I want to be able to sync the data between my work and home computers. (And I wanted a learning project for developing Sync apps!)

One problem: in development, I’m making breaking schema changes often. And unlike local Realm development, you can’t just delete the local Realm file to use the new schema: you have to terminate Sync, blow away your schema and data, and then start Sync again with your new data model. I’ve taken a more nuclear option and I just delete the Realm app, drop the MongoDB Atlas database, and create a new Realm App.

In either case, doing all this stuff manually takes way too long. So I wrote my first bash script to automate it. Hope this helps other Realm Sync developers, or even just provides some inspiration to automate away some annoying, repetitive task!

https://dev.to/dacharyc/automate-realm-app-rebuilds-3cjn

Wow

Sat, 12 Mar 2022 15:57:22 -0500

Wow. Overnight, the tiny hobby app that I wrote to help me keep track of NPCs, Locations and Quests in Elden Ring reached #1 in its category on the App Store. It has been hovering between 1 and 2 ever since.

This is surreal. I wrote this app in two weekends and a handful of weeknights. I’ve been through tutorials and online courses but have had no formal CS education and don’t consider myself a “real developer.” Yet here we are. I’ve shipped an iOS app that people are buying.

This is what imposter syndrome looks like.

It is approved!

Tue, 08 Mar 2022 21:39:26 -0500

It is approved! I have my first iOS app on the App Store!

If you are into video games, and happen to be playing Elden Ring, you might want to check it out. It’s an RPG play through tracker where you can keep track of NPCs, Locations and Quests in your game. Keep tabs on locations you’ve cleared (or haven’t), quests you’ve completed (or haven’t), notes about all of the above… I needed something more organized than a notebook.

(Bonus, this is also great for TTRPG tracking - I’ve started using it for two of my D&D games!)

https://shatteredring.com

Just submitted my first iOS app to the App Store!

Tue, 08 Mar 2022 00:17:09 -0500

Just submitted my first iOS app to the App Store!

When I started working for MongoDB, I had gone through some programming courses but didn’t really know how to even start writing an app. I have learned so much from my awesome teammates, and from working on the code examples & docs for the Realm Swift SDK. Major shout out to @cbush for being an awesome lead who has patiently and gently mentored as I’ve worked to grow my coding skills.

MongoDB talks about being an inflection point in people’s careers. It has definitely been one for me. I’ve had app ideas I’ve wanted to work on, but just never quite figured out how to get from idea to finished app. I know I still have a ton to learn, but I feel like this is a major milestone that has “unlocked” my ability to create the apps I want to use. And no, I’m not interested in becoming a full-time developer - I love the combination of technical writing and writing code that we do on my team - but now I feel empowered to write tools and the little hobby apps I’ve been yearning for.

Here’s hoping the App Store reviewer is having a good day 😉

An interviewee asked me yesterday if I was still at MongoDB in 5 to 7 years…

Tue, 15 Feb 2022 09:12:41 -0500

An interviewee asked me yesterday if I was still at MongoDB in 5 to 7 years, how would I feel about that? Would I be happy about it?

Obviously things can change, but at the moment, yes, I am planning to be at MongoDB that long and anticipate still being happy to be here.

I have freelanced for most of my career because it gives me flexibility, and I like being free to do the work that appeals to me. Freelancing gave me the opportunity to always be learning new things, and to pivot if I got bored.

But I love my work at MongoDB, and the freedom my manager gives me to pursue the projects that are interesting to me. I feel supported and valued by my teammates. I am surrounded by smart people who help me grow. The work itself is satisfying.

I can honestly say that MongoDB is the first place in my career that I feel I’ll be happy and want to stay for a very long time.

Thank you to the interviewee for helping me realize that! And may we all be as happy with our work.

It has been an awesome week at MongoDB!

Fri, 10 Dec 2021 20:26:58 -0500

It has been an awesome week at MongoDB! We just wrapped up our second week-long hackathon of 2021.

On one hand, it feels extravagant for a company to tell people to go work on something interesting for a week that isn’t on the critical path.

On the other hand, this is the second time this year that I’ve written a new app in a week, using different aspects of our product like a developer would and learning a ton.

As an employee, I’ve really valued the opportunity to pick up new tech and devote a solid block of time to it, versus the nights and weekends of peacemeal learning I’d have to do alongside my regular day job. It’s great for my continuing education as a developer, and it’s also great for my mental health and general motivation to make real progress on a “for fun” project.

It’s also great for the company for me to use different aspects of our tech. It gives me first-hand experience to use in crafting our docs and code examples, and there are definitely places I’m planning to improve. It also gives me empathy for the devs who use our products on a daily basis, and a new understanding of different tasks and user journies that might make their lives easier. (And let’s not forget - some of the awesome hackathon projects actually make it into the company products as new features - talk about a success story!)

Huzzah for another hackathon! Learned a ton and am feeling rejuvenated for work going into the winter.

(Oh, and what did I work on? I wrote a SwiftUI app that uses Realm Database and Realm Sync to persist data to MongoDB Atlas. I’ve started a couple of personal projects with this tech but haven’t finished any of them - learned a ton I can apply to my hobby apps and hopefully get them going soon! And I got to look at pictures of cute dogs. What’s not to like? 😁)

You can learn a lot about company culture by how they treat you when things happen

Wed, 01 Sep 2021 10:14:11 -0400

You can learn a lot about company culture by how they treat you when things happen.

I had major surgery in 2019, less than ~6 months after starting to contract full-time with Lullabot. I let my contacts know what was happening, and that I'd probably be out for 6-8 weeks while I was recovering. As a contractor, I fully didn't expect they'd want to hold a position open for me that long - I figured they'd just want to bring in another contractor to keep things going. But I let them know that I wanted to keep working with them, and they said the feeling was mutual.

They waited for me to recover. Never once did they push for me to come back before I was ready. They sent flowers, and were super supportive as I eased back into working as many hours as I could, until I was back to full-time again. That understanding and generosity of spirit is a true indicator of a positive company #culture - far beyond the superficial "we have free snacks" and "it's so much fun to work here" that you often hear from recruiters and in job pitches.

I'm thinking about this as hubby has a scheduled surgery in ~6 weeks. I wonder what his experience will be like. Guess we'll find out the truth about his company's culture!

As a technical writer, I’ve been an admirer of Stripe for years

Thu, 10 Jun 2021 15:03:56 -0400

As a technical writer, I’ve been an admirer of Stripe for years. They’re well-regarded in the industry for having great docs that other orgs look to for inspiration. I was excited when a talented docs leader I follow got an offer from Stripe last week. “What a great match,” I thought.

Today, she shared that Stripe had rescinded her signed offer. They told her it was “due to changing company priorities.”

Now, I’ve lost respect for a company that I’ve admired for years. This isn’t how you treat people. I’m very disappointed.

This talented docs leader has a lot of followers; a few hours after sharing this news, she has already gotten hundreds of likes and comments. I hope she’ll land someplace that values the skills she’ll bring to the org.

You’ve missed out, Stripe, and you’ve alienated a small community. It’s not a good look.

Today I started an exciting new role as an Education Engineer on the Developer…

Tue, 19 Jan 2021 22:56:10 -0500

Today I started an exciting new role as an Education Engineer on the Developer Education team at MongoDB. I'm so excited to have the opportunity to leverage my documentation skills and grow my coding skills to help developers succeed with MongoDB Realm. (Did I mention I'm excited?)

I already miss my Tugboat and Lullabot peeps, but as one of my former colleagues said, "That sounds like such a Dachary role." I couldn't resist it. Fortunately, I'm meeting lots of smart, talented folks at MongoDB who I know will keep me on my toes and help me grow.

Feeling blessed and well-supported as I take this next step in my career.

Was recently reminded of this moment

Thu, 24 Sep 2020 23:10:02 -0400

Was recently reminded of this moment: the culmination of a four-month motorcycle trip spanning nearly 18,000 miles across 13 countries, from Boston to Ushuaia.

I learned a lot of important lessons on that trip that have made me the person I am today. But one of the most valuable was the knowledge that whatever obstacles are thrown in my path, I can figure out a way over, around, or through them and keep moving forward.

That lesson has gotten me through so many hard days and hard times, both at work and in my personal life.

https://flic.kr/p/9qrJaw

Exciting announcement time

Mon, 13 Jul 2020 18:07:03 -0400

Exciting announcement time: after 14 years as a contractor, I've finally hung up my freelance hat to go to work full-time for Tugboat !!!

As of today, I'm officially starting as "Technical Content Strategist" for Tugboat; a role that's part marketing, and part technical documentarian. I'm so excited to be joining the talented team alongside Ben Chavet, James Sansbury, Matt Westgate (he-him), and a TBA additional member of our crew ;)

Many thanks to the Tugboat crew for making me feel like a member of the team in the past year while I've been contracting for them, even before making the transition to full employee. I'm so delighted to make it official!

And thanks to the Lullabot leadership team, our parent company, for taking the leap of faith to devote resources to this awesome tool. I've really enjoyed working with the Lullabot crew, and am so glad to be joining the team.

This is a deeply weird time, and none of us can predict what the future holds, but I am filled with optimism to be joining this team and seeing what we can accomplish together.

In a month of part-time work at my new #technicalwriting gig, I have spun up on…

Fri, 12 Jul 2019 16:00:40 -0400

In a month of part-time work at my new #technicalwriting gig, I have spun up on their #software, crash-coursed on a couple of ancillary #technologies, consumed all of their existing documentation, built out a matrix for their #documentation redesign, and created a new version of their doc site.

The new doc site translates to 106 pages when printed as a PDF. Probably ~70-80 pages of that is new material. I'd estimate I have another 10-15 pages to draft, and then I might be able to reduce the volume of docs by tightening up the new organization a bit, and removing some stuff through content reuse.

Not bad for a month of part-time work!