> At this point, most tech writing shops are serving llms.txt files and LLM-optimized Markdown
I find this hard to believe. I‘m not sure I’ve ever seen llms.txt in the wild and in general I don’t think most tech writing shops are that much on the cutting edge.
I have seen more companies add options to search their docs via some sort of AI, but I doubt that’s a majority yet.
Tangentially related: for those of you using AI tools more than I am, how do LLMs handle things like API updates? I assume the Python2/3 transition was far enough in the past that there aren't too many issues. How about other libraries that have received major updates in the last year?
Maybe a secret positive outcome of using automation to write code is that library maintainers have a new pressure to stop releasing totally incompatible versions every few years (looking at Angular, React...)
A good fraction of my CLAUDE.md lines is along the lines of "use X, not deprecated Y." The training input has more instances of the old API use, and they all keep popping up repeatedly, even with those instructions.
I think something people really misunderstand about these tools is that for them to be useful outside of very general, basic contexts, you have to already know the problem you want to solve, and the gist of how to solve it - and then you have to provide that as context to the LLM.
That's what the point of these text documents is, and that's why it doesn't actually produce an efficiency gain the majority of the time.
A programmer who expects the LLM to solve an engineering problem is rolling the dice and hoping. A programmer who has solved an engineering problem and expects the implementation from the LLM will usually get something close to what they want. Will it be faster than doing it yourself? Maybe. Is it worth the cost of the LLM? Probably not.
The wild estimates and hype about AI-assisted programming paradigms come from people winning the dice roll on the former case and thinking that result is not only consistent, but also the same for the latter case.
To put it bluntly, the current state of AI often comes down to this: describing a problem in plain English (or your local language) vs writing code.
Say, “Give me the stock status of an iPhone 16e 256GB White in San Francisco.”
I still have to provide the API details somewhere — whether it’s via an agent framework (e.g. LangChain) or a custom function making REST calls.
The LLM’s real job in this flow is mostly translating your natural language request into structured parameters and summarizing the API’s response back into something human-readable.
I will just say that AI is forcing me to document and write a lot more than I used to, and I feel it's super boring yet beneficial for everyone, there are no more excuses to procrastinate on those aspects.
The difference from before was: all stakeholders lived on a shared yet personal interpretation of the domain (business, code, whatever). This often leads to wastes of times, onboarding issues, etc, etc.
LLMs are forcing me to plan, document and define everything, and I think that's making the codebases/documentation/tests/prs and myself all better.
It makes sense that technical writers would make the best Vibe Coders.
Giving the LLM a clear, thorough, fluent description of the system requirements, architecture, and constraints sufficient to specify a good implementation.
AI reads your “prompt”, but you have to very specific and to know what and how you want achieve it.
Typical example is when you’ve asked about JSON once then Claude or ChatGPT starts to think that you want everything with JSON. :)
I have spent last two months using Google Gemini with 1 mil token window, and I have to say - inaccurate assignment leads to inaccurate result. And time really runs by days.
On the other side, I wouldn’t be able to have anything without it, as I am solo plus a bad coder :)
But you have spend a lot of time with writing and refining the assignment.
Sometimes it was better to start over than to end up in a dead end after 2-3 hours of wrangling the code from ai.
AI probably knows all main documentation. But in case you want to give more documentation before starting a project, just upload it as markdown.
I think it is good to write good documentation, whether or not you use LLMs. I do not use LLMs but I still try to write good documentation because it is helpful to have good documentation even if you do not use LLMs.
However, it is not my intention to write documentation specifically for use with LLM, or for LLMs to scrape my servers for this purpose. If someone wants to use them with LLMs they will have to do that by themself, which you are free to do.
I've been finding adding context for your external packages is really important when the package is relatively new and or has breaking changes since the model training cut-off date.
Two that stick out this week are google's genai (client for vertex/gemini ednpoints) that is updating methods and moviepy in their 2.x breaking changes (most of the corpus for this library was trained with v1.x).
17 comments
[ 3.1 ms ] story [ 50.2 ms ] threadI also see it in mostly spaghetti code bases, not in great code bases where no one uses "AI".
I find this hard to believe. I‘m not sure I’ve ever seen llms.txt in the wild and in general I don’t think most tech writing shops are that much on the cutting edge.
I have seen more companies add options to search their docs via some sort of AI, but I doubt that’s a majority yet.
Maybe a secret positive outcome of using automation to write code is that library maintainers have a new pressure to stop releasing totally incompatible versions every few years (looking at Angular, React...)
That's what the point of these text documents is, and that's why it doesn't actually produce an efficiency gain the majority of the time.
A programmer who expects the LLM to solve an engineering problem is rolling the dice and hoping. A programmer who has solved an engineering problem and expects the implementation from the LLM will usually get something close to what they want. Will it be faster than doing it yourself? Maybe. Is it worth the cost of the LLM? Probably not.
The wild estimates and hype about AI-assisted programming paradigms come from people winning the dice roll on the former case and thinking that result is not only consistent, but also the same for the latter case.
Say, “Give me the stock status of an iPhone 16e 256GB White in San Francisco.”
I still have to provide the API details somewhere — whether it’s via an agent framework (e.g. LangChain) or a custom function making REST calls.
The LLM’s real job in this flow is mostly translating your natural language request into structured parameters and summarizing the API’s response back into something human-readable.
The difference from before was: all stakeholders lived on a shared yet personal interpretation of the domain (business, code, whatever). This often leads to wastes of times, onboarding issues, etc, etc.
LLMs are forcing me to plan, document and define everything, and I think that's making the codebases/documentation/tests/prs and myself all better.
What we find (or used to find) interesting (hacking code), the AI is doing and what we used to hate doing (writing documentation) we do that now.
Truly bizarro world we live in.
We revamped our docs for AI-driven development - https://news.ycombinator.com/item?id=44697689 - July 2025 (35 comments)
Giving the LLM a clear, thorough, fluent description of the system requirements, architecture, and constraints sufficient to specify a good implementation.
Typical example is when you’ve asked about JSON once then Claude or ChatGPT starts to think that you want everything with JSON. :)
I have spent last two months using Google Gemini with 1 mil token window, and I have to say - inaccurate assignment leads to inaccurate result. And time really runs by days.
On the other side, I wouldn’t be able to have anything without it, as I am solo plus a bad coder :)
But you have spend a lot of time with writing and refining the assignment.
Sometimes it was better to start over than to end up in a dead end after 2-3 hours of wrangling the code from ai.
AI probably knows all main documentation. But in case you want to give more documentation before starting a project, just upload it as markdown.
However, it is not my intention to write documentation specifically for use with LLM, or for LLMs to scrape my servers for this purpose. If someone wants to use them with LLMs they will have to do that by themself, which you are free to do.
Two that stick out this week are google's genai (client for vertex/gemini ednpoints) that is updating methods and moviepy in their 2.x breaking changes (most of the corpus for this library was trained with v1.x).
I wrote about some findings here, and that there's still not a great way to have the models examine only the pieces of documentation that they need for their work: https://github.com/sutt/agro/blob/master/docs/case-studies/a...
Anything you can do to provide additional context in your codebase will improve your results.