• 2 Posts
  • 13 Comments
Joined 13 days ago
cake
Cake day: November 9th, 2026

help-circle
  • Sure, I might actually need a bit of help myself for your first question ;)

    What do you mean by: “How is this actually different from normal software documentation distribution besides the standardised location for it?” Could you provide some examples and explain a bit more what you mean by normal software documentation distribution?

    Thank you for bringing up the Linux ecosystem. This example is real but notice who ships the docs: the distro maintainers, not upstream. Debian and friends ship man pages in the main package (although some argue that this practice is dying) and the longer prose docs are often split into separate -doc sub-packages, which is the ‘second box’ argued against in the white paper (section 3.5). The upstream artifact usually ships light-weight documentation such as the README.md file and a URL for more thorough documentation.

    More importantly, AI coding agents do not usually work against distro packages. They work against npm, PyPI, Maven, crates.io, etc. In most of these ecosystems, the norm is code plus a thin README that points at a website.

    The react-query example you mention isn’t quite the exception for complete thorough documentation outside of the installed artifact. We have: docs.rs, Read the Docs (For 2021, Read the Docs reported 700 million page views and 196 million unique visitors - it would be awesome if we had more recent stats but could not find any), GitHub Pages, vendor portals, etc. The README that ships with the package is usually a logo, a one-liner, an install snippet and a link. It’s a pointer, not full documentation inside the installed artifact.

    Besides the standardised location, CoDoc is doing a lot more than meets the eye. Location might be the least of it:

    • A catalog index (index.md) so an agent reads only what’s relevant, within context limits
    • Version-matching by construction: the registry artifact is immutable, the docs within the installed artifact are there forever
    • Offline and deterministic: works in air-gapped environments, byte-identical every time
    • Content designed for the agent: usage guidelines, do/don’t rules, complete runnable examples
    • Discovery: the agent can expect docs to be there without a human pointing (if the convention gets widespread adoption, it lives in the models’ training data, not in the repo’s config)

    The Linux precedent actually supports the CoDoc proposal. The OS world shipped docs in the box because the consumer on the machine needs them locally. CoDoc extends that logic to the language ecosystems, where the consumer on the machine is now increasingly (and I would dare say primarily) an AI agent that reads files.

    If the README were enough, Vercel’s evals wouldn’t show 100% vs 53% on APIs absent from training data. The readme didn’t move that number. Complete, version-matched, bundled docs did.

    Now, the last two questions:

    Why would projects decide to use this method which further bypasses their potential alternative revenue streams or existing documentation?

    First, CoDoc does not take the website away. The docs site stays exactly where it is for humans. As a first step, CoDoc can add a generated machine-readable copy inside the artifact, built from the same source of truth (see section 8.7 of the paper). It is additive. react-query keeps its ad revenue stream, your AI coding agent just stops inventing v5 APIs.

    Second, the incentive is being chosen as the library for your project. Section 7.3 in the paper discusses the virtuous cycle for libraries that adopt CoDoc: libraries that work well with agents get picked, so maintainers ship docs to stay competitive. This is not hypothetical at all. Design Factory and Next.js now ship their full documentation inside the package, and Vercel’s own evals quoted above are what measured the effect. The TypeScript ecosystem already lived through this transition before. It is best read in Section 12 of the paper. Developers will start asking “does it ship with CoDoc?” the same way they asked “does this library have first-party types?”.

    “What poorly documented project is going to adopt this and suddenly write good docs?”

    None of them, and CoDoc does not pretend otherwise. CoDoc is a proposed industry standard. Section 8.7 says this out loud under “a note on documentation maturity”. It cannot manufacture documentation that does not exist. The paper gives libraries an incremental ladder (see section 10.9)

    P.S. With your genuinely good questions, you forced me to go back to re-read the paper and do some research. I am now more convinced that CoDoc is the way forward for cheap, fully-local AI-driven development and that there really is a place for CoDoc as a cross-ecosystem standard.


  • You say Opus 5.5 “gets 100% anyway” but did you read the footnote?

    • AGENTS.md points agents to bundled Next.js documentation. Both conditions can access these docs. With AGENTS.md shows the success rate with that initial guidance.

    All models including the frontier models had the bundled docs available the whole time. Your 100% just shows that the AGENTS.md pointer wasn’t necessary for some of them. Which is, if anything, another point for CoDoc ;)

    Now here’s the part you skipped: GLM5.2 (open-weight model) also hit 100% with the AGENTS.md guidance, at 32% less cost than the Opus 5.5 you use “basically 100% of the time.” So the frontier model isn’t magic. The context is. And that context is free with CoDoc for all models.

    “It’s a very conservative estimate based on my experience.” So it was a vibe after all… And your vibe, built on:

    • “I haven’t checked these, but go and look at e.g. LLVM, Git, libpng, SDL, Qt, etc.”

    Cherry-picking five eyeballed repos as evidence for “50% of software” is just hilarious. And you’re mixing up two different things. I didn’t ask whether docs live in the same Git repo. I asked whether libraries ship complete, AI-optimized documentation inside the package artifact. So here we have someone who eyeballs five repos and calls it a “very conservative estimate.” 👏

    “Frontier models are happy to reverse engineer binaries without prompting. Reading a bit of source code is nothing to them.” Great, here we have someone advocating for letting frontier models waste compute power and frivolously consume your tokens to do what co-packaged documentation does for free. How about we put some of those data centers next to your place?

    And by the way, two things:

    1. The paper disarms your argument of models looking at source-code, section 10.5 if you care to read it. There is a reason why humans have built documentation wikis, sites and portals for years.

    2. You might want to read this: Claude Opus 5.5 Reverse Engineering Refusals

    “No I’m not dumb enough to use dynamic typing.” The point was never about typing. It was about a model hallucinating your v5 API signatures.

    Since you use Opus 5.5 basically 100% of the time, let me recall something for you. On June 12th, a single export control letter switched Fable 5 off for every customer worldwide for 17 days. Opus 5.5 is one letter away from the same fate. Besides, even if they do not share the same fate via the export control letter, the company behind the model you rely on is not profitable (it is actually very far from it). As you may know, it will soon IPO to finance their operations and service their existing debt. The irony: they have frontier models under their fingertips, yet their own models cannot solve their business model or their financing problems. You are more than welcome to put all your oranges in one basket.

    TLDR: a vibed estimate from five unchecked repos, completely dismissing the benefits of CoDoc for ecosystems with dynamically-typed languages, and a frontier model that “gets 100% anyway” which sure, it does: with the bundled docs that CoDoc ships.

    I’ll be here if you want to come back with solid evidence. If, however, you do not want to show the evidence behind your claims and you just wanna play the trust me bro game, please play it with some naive people. It ain’t gonna work with me ;)


  • I would say maybe 50% of software already does that.

    Would you care to show some evidence, or is it a vibe?

    For example 100% of Rust crates ship the docs with the code.

    True, and that’s actually a point for CoDoc, not against it. Rust already does the right thing. The question is what the other 90% of the whole software ecosystem is doing.

    AI will happily skip the docs and just figure things out from the source code, which is usually better anyway.

    Show us the evidence. Vercel’s evals say the opposite: 100% pass rate with bundled docs vs 53% without, on APIs absent from training data. It got it wrong 47% of the time. The docs weren’t skipped… they were the difference.

    Using which model? They don’t say? Huh.

    Let me save you some tokens: https://nextjs.org/evals

    Frontier models very rarely hallucinate anymore, and they’re actually really good at writing tests now

    How does that address a frontier-model hallucinating your v5 API signatures? Would you like to find this out at runtime and burn more tokens for the corrections?

    Spoiler: If you look at the Next.js evals here you will see that even GPT 6 Astra (high) benefits from bundled documentation.


  • Not surprised that your neighbors haven’t heard of them…

    What really surprises me is your claim here: “any software engineer worth their salt has” heard of Amadeus. So the bar for being a competent software engineer is now name-recognition of a specific travel-tech company? Let me pass that to HR: “have you heard of Amadeus?” is going straight into our next interviews.

    And as for your AI-generated diatribe claim, I invite you to look up the meaning of diatribe. A well articulated and thought-provoking post is not a diatribe.

    • Post and comment 100% written by a human, in case you had any doubts :)


    • CoDoc (Co-packaged Documentation) is a standard advocating for colocating AI-optimized documentation next to the code installed for each software library used in your project.

    • Understand-Anything is a Claude Code plugin that maps your existing codebase into a knowledge graph.

    They are complementary. Software libraries following CoDoc would supply additional files and directories for each dependency in your project enriching the output of the Understand Anything plugin.

    I also understand that they solve different problems. CoDoc would allow an AI agent to operate in auto-pilot mode (with less AI slop) by having all the necessary context locally for all your project’s dependencies. CoDoc enables the AI agent.

    Understand Anything maps your codebase to help you navigate and understand a complex codebase (it builds a JSON graph). Understand Anything enables the human software engineer.





  • You called it “pure drivel” and then quoted the one line that’s a file-naming convention, not the argument… The moat in CoDoc is that the documentation ships inside the package, version-matched, offline, deterministic. Can you tell me what proportion of software libraries today ship complete AI-optimized documentation within the library’s artifact? I’ll wait.

    And to your frontier-model guess, the models behind the research agents are: Opus 5.5 and Astra. So no, not slop.

    As for “open weight models are nowhere near the capabilities of frontier models”: sure, on raw benchmark scores (but they always end up catching up). Vercel’s evals on Next.js 16 APIs (absent from training data) show 100% pass rate with bundled docs vs 53% without. As stated in the post, the bottleneck for a 27B local model isn’t raw intelligence, it’s context. CoDoc fixes the context for free. A 27B on your laptop with the right context can beat a frontier model that’s hallucinating your v5 API signatures.

    Keep letting the Goliaths vacuum your code, your tokens, and your money. The fizzy orange drink is on them.

    P.S. Post and comment 100% written by a human, in case you had any doubts :)