This is facts. All of this talk about putting agent skills directly into repos (as Markdown!) is maddening. "Where were LITERALLY ALL OF YOU whenever the topic of docs as code came up?"

This is doubly maddening with NotebookLMs. They are becoming single sources of knowledge for large domains, which is great (except you can't just read the sources, which is very "We will read the Bible to you" energy), but, in the past, this knowledge would've been all over SharePoint, Slack, Google Drive, Confluence, etc.

I've chose to embrace the silver lining where there is now business backing to prioritize all the devx/documentation work because it's easier to quantify the "value" because LLM sessions provide a much larger sample size than inconsistent new hire onboarding (which was also a one-time process, instead of per session).

I do think people are going way overboard with markdown though, and that'll be the new documentation debt. Needs to be relatively high level and pointers, not duplicate details; agents can parse code at scale much faster than humans.

> Where were LITERALLY ALL OF YOU whenever the topic of docs as code came up?

Docs as code is still writing and not coding. Those are simply different skills. As programmers, we find coding to be fun and glamorous and writing to be difficult. Emotionally, it's much easier to finish a piece of code and feel genuinely happy with it (you are proud of your achievement) than it is to write a paragraph of docs and feel genuinely happy with it (you can feel in your bones that it's not good but you don't know how to improve it and you just want it over with). We have not built anywhere near the level of skill for writing than we did for coding when we wrote our own little programs for ourselves and never built a habit of thinking about how other people would interact with our code.

(For me, this is exacerbated by having been more isolated from other people than the average population, partly due to neurodivergence and partly because the hobby was niche at the time, and I assume this is also true of a lot of people currently employed as professional programmers.)

Haha indeed. At work suddenly documentation and APIs are important, but it's all for/behind "skills". Before it was always "sure, that would be nice"...

I do welcome the improvements to doc and APIs this brings though!

My favorite thing is when some projects now have better documentation in their Claude skills or MCPs than they ever did for users.

There is natural incentive for engineers working on a project to keep Claude skills up to date. I cannot say the same for general documentation.

But maybe not for long. When we get long-running AIs, the knowledge locked inside the AI's thinking might supplant docs once again. Like if you had an engineer working at your company for a long time and knowing everything. With all the problems that implies, of course.

at any time you can ask the model to produce documents given the latest state of the code base and at an altitude you choose.

That's the weird best thing about LLMs - there is finally incentive for projects to create documentation, CLIs, tests, and well organized modular codebases, since LLMs fall flat on their face without these things!

Yeah, I joined a project a couple of months ago, felt completely lost.

Last week, a colleague finally added for Claude all the documentation I'd have needed on day one. Meanwhile, I'm addressing issues from the other direction, writing custom linters to make sure that Claude progressively fixes its messes.

But that documentation itself is likely AI-generated

At least it saves me from having to generate the docs myself!

Why continue involvement with a project that clearly devalues their “customers” or “users” who care about documentation?

Projects that spend time on documentation for my robots have shown me they care about my use case!

I feel like Google search results have gotten tremendously worse over the past 2 years too. It's almost like you have to use AI search to find anything useful now.

Which of course reduces traffic to sites and thus the incentives to create the content you're looking for in the first place :(

I actually think the AI Overviews from Google have improved a lot in the last 2 years. They used to be trash. And now they are often good-enough so that I do not even switch to ChatGPT anymore.

The traditional search results suffer a lot because AI and AI content generation have enable a lot of aggressive SEO/spam plays.

There’s many groups that “win” by making search results worse. It’s an ongoing battle between them, and if someone’s blaming solely Google for it, they’re way oversimplifying.

I totally agree with you, this reduces the traffic to sites but also there were lots of website that information wasn't true or correct.

Does anyone know which tool can be best used instead of Google for "classic", non-AI googling?

Pure non-AI googling will not work since many websites now use AI to create content. And so far, no search engine has managed to reliable detect and filter that out.

Kagi

> I often wonder how much more productive I'd be if just a fraction the effort and money poured into LLMs was spent on better API documentation and conventional coding tools.

Probably negligible. It's not a problem you can solve by pouring more money in. Evidence: configuration file format. I've never seen programmers who enjoy writing YAML. And pure JSON (without comments) is simply not a format should be written by humans. But as far as I know even in the richest companies these formats are still common. And the bad thing they were supposed to replace, XML config, was popularized by rich companies too...!

Programmers don’t enjoy writing things they have no good understanding of, and no good way to ascertain or predict in advance, how exactly it will behave. That’s at least partly due to poor documentation. Good documentation gives you a reliable conceptual model and makes you confident about how to use a tool.

I love YAML, so there is at least one weirdo out there on the internet who is bitter that TOML and JSON won

As a TOML and JSON fan I must say those formats definitely didn't win :). YAML did, by a really long shot too unfortunately

JSON is not designed as a configuration file format.

Yeah I get this impression too. AI feels like it's papering over overwrought and badly designed frameworks, tech stacks with far too many things in them, and also the decline of people creating or advocating for really expressive languages.

Pragmatic sure, but we're building a tower of chairs here rather than building ladders like a real engineering field.

As someone who does broad activities, it supercharges a lot of things. Having a critical eye is required though. I estimate 40%-60% improvements on basic coding tasks.

I don't bring huge codebases to it.

And hilariously, the worst offenders are AI frameworks themselves. A couple months ago I was helping a client build out some "agentic" stuff and we switched from OpenAI Agents library to Agno. Agents is messy enough, like making inconsistent use of its own enums etc, but with Agno you can really feel that they are eating their own dog food. Plenty of times I literally could not find the API for some object, and of course their docs page pushes you toward chatting with their goddamn docs chatbot, which barfs up some outdated function signature for you.

I can't speak for your efficiency, but for me it's now often easier to create a tool than find if one exists and learn how to use it.

I was able to one-shot a parameterized SVG template creator for a laser cutter. Unlikely I could have achieved the same with 40 hours of pure focus.

> better API documentation and conventional coding tools

Agreed, and it depends on the language I suppose. I'm a C++ developer and when you start working with templates even at a non-casual level, the compiler errors due to either genuine syntactic errors or 'seems correct but the standard doesn't support' can be infuriatingly obtuse. The LLM 'just knows' the standard (kind of, all 2k pages), and can figure out and fix most of those errors far faster than I can. In fact one of my preferred usages is to point Codex at my compiler output and get it to do nothing more than fix template errors.

Kotlin, for example, is much more in your face, in the IDE which does a correctness pass, before you even invoke the compiler (in the traditional sense) and the language spec is considerably leaner with less (no?) UB, unlike C++.

Depends on which C++ we are talking about.

You can have the Kotlin experience with a mix of static asserts, constexpr and concepts.

C++ IDEs also offer many goodies which those that insist in using vi and emacs keep missing out.

Can’t you make the LLM write API documentation?

I agree. I think of AI as a search engine on steroids.

But I think it IS the best way to search for information, to be able to put a question in natural language. I'm always amazed just how exactly on-point the answer is.

I mean even the best of docs out there that have a great search bar like the Vue docs still only matches your search term and surfaces relevant topics.

then you should be delighted we have LLMs one of the use cases they are best suited to is writing documentation, much better than humans can.

Good is debatable. The docs I want point out the weird shit in the system. The AI docs I've read are all basically "the get user endpoint can be called with HTTP to get a user, given a valid auth token". Thanks, it would have been faster to read the code.

They write good _looking_ documentation. How good those docs are is entirely on the person/people who prompted them into existence.

Please don't inflict LLM docs on people