Docs engineer here. Nice to read about writing style: would you consider creating a writing benchmark at some point? I guess y'all are painfully aware of the load-bearing issues (pun intended).

good catch!

Seeing all the questions in this thread, I strongly recommend Dachary Carey's post on the topic of agent-ready docs: https://dacharycarey.com/2026/02/18/agent-friendly-docs/

I think it's easier to serve those bits as Markdown to agents only through content negotiation.

Agreed on the first experiment, that's why the post says it hit the ceiling. The others are not saturated. I'd love to find a way of making the first experiment more discriminating.

Code doesn't explain best practices, architectural concerns, and so on. Best combo? Docs + code.

It also redirects the agents from adding enormous sloppy comments in the code - I have a linter that only allows 1 line comments with a reference to a docs folder tag `See BOB-IS-UNCLE.md`

Then you can ruthlessly prune the docs folder on PR review and regular passes when e.g. claude really wants to write a novel about the glorious intricacies of bugs it's solved.

Indeed. Another thing worth exploring is how much the position of instructions matter; Claude claims to read docs as a whole unless they're very large, though it might be that it only grabs the first lines of a doc sometimes, in which case there is an "above the fold" effect.

I wonder if there's room for a Linux distro á la Microsoft Bob. :)

http://toastytech.com/guis/bob.html

ha this is the first time i've seen this but honestly yes, if there was an accessible enough for a 4 year old OS to "explore" around in to find the applications I would be throwing it on the USB as I type

On one hand I'd love to browse the site; on the other, my PTSD would prevent me from doing so.

I wonder if ads will be sort of elegant and contextual, like product placement in screenplays.

"I've completed the analysis. One moment...

_Takes a sip of Evian_

Ahhh. Now where were we? Ah yes. Here are the results:"

I wonder if these models, left running in an air-gapped environment, would end up developing honeypots for the first human to log in.