I use AI to write documentation frequently. An AI agent, 600k tokens into a feature that it just authored, understands the feature as well or better than I do. It can document, compactly, what the code actually does, as well as the intent. These docs add value above having no docs and letting another AI, with zero context, read your bare code.
In the context in which I work, the quality of these docs is sufficient.
Unless your docs are being read by thousands of people, in 2026, in most contexts, handwriting docs adds less value than writing high quality instructions to your agent.
There are exceptions. For example, when kicking off a project, short crisp prose in a product brief aligns a team, removes uncertainty, and clarifies decisions. These are worth hand writing.
IMHO lossy/lossless feels like the wrong term to use for natural-language text.
Every time natural-language passes from one human to another whether verbally or in the written word, there is a greater than zero percent chance that the meaning will be received/understood in a way that is "lossy" compared to the communicating party's intent. The so-called "telephone game" is a very good example of this.
It seems true that the lossy problem arises even without any LLMs or any intentional transformations.
Lossless in other domains basically means perfect-fidelity carried across copies. Natural language seems almost incapable of this ideal.
8 very different messages all containing the same words in the same order. If the emphasis is changed or lost between sender and receiver, the message itself is lost regardless of the faithful reproduction of the actual words.
“If you generate a document from a short prompt then ask your readers to go through the longer output, you are disrespecting their time. They can always talk to ChatGPT themselves if they want to.”
Ok but the idea is that you can throw in all your files a stream of consciousness barf and then get something readable that conveys the point better than you could have done with decades of practice. And the best systems would probe you at whatever meta level you stop caring about.
Another way this could go is that you simply don't need to communicate your ideas to another person anymore, that everyone hyper-specializes into their own language, if not just straight up the AI scanning your brain.
These are very well formulated rules about how to use an LLM to write documentation.
> Writing is thinking. Spending time on the writing process — on deciding what to emphasize and how to structure your ideas clearly — teaches you more about your topic. If you circumvent this process, you will probably walk away with a poorer understanding of the subject matter.
This is a point with which I completely agree.
It is extremely frequent that only when you write a detailed documentation for the product that you have designed, you finally understand some of its finer points, which perhaps need some last-minute changes, to prevent future problems.
Because of this, I despise the companies where the project plans do not allocate an adequate time for writing documentation, believing that this is some kind of unproductive activity. I have worked at many companies, in many countries, and without exception the best productivity, measured in the rate of completing projects that worked OK in production or at customers, was at the companies where the project schedules seemed to be more relaxed, by allocating a generous time for writing documentation.
Also when I was a child, much of what I did learn I learned by trying to explain those things to my schoolmates, and this was significantly more than I had learned directly from teachers.
I use AI to write documentation frequently. An AI agent, 600k tokens into a feature that it just authored, understands the feature as well or better than I do. It can document, compactly, what the code actually does, as well as the intent. These docs add value above having no docs and letting another AI, with zero context, read your bare code.
In the context in which I work, the quality of these docs is sufficient.
Unless your docs are being read by thousands of people, in 2026, in most contexts, handwriting docs adds less value than writing high quality instructions to your agent.
There are exceptions. For example, when kicking off a project, short crisp prose in a product brief aligns a team, removes uncertainty, and clarifies decisions. These are worth hand writing.
I don't know about that. There's no understanding anywhere at that point.
> handwriting docs adds less value than writing high quality instructions to your agent
Are the instructions not docs?
IMHO lossy/lossless feels like the wrong term to use for natural-language text.
Every time natural-language passes from one human to another whether verbally or in the written word, there is a greater than zero percent chance that the meaning will be received/understood in a way that is "lossy" compared to the communicating party's intent. The so-called "telephone game" is a very good example of this.
It seems true that the lossy problem arises even without any LLMs or any intentional transformations.
Lossless in other domains basically means perfect-fidelity carried across copies. Natural language seems almost incapable of this ideal.
SHE said she did not take his money.
She SAID she did not take his money.
She said SHE did not take his money.
She said she DID not take his money.
She said she did NOT take his money.
She said she did not TAKE his money.
She said she did not take HIS money.
She said she did not take his MONEY.
8 very different messages all containing the same words in the same order. If the emphasis is changed or lost between sender and receiver, the message itself is lost regardless of the faithful reproduction of the actual words.
“If you generate a document from a short prompt then ask your readers to go through the longer output, you are disrespecting their time. They can always talk to ChatGPT themselves if they want to.”
bars!!
How about gainful transformation of natural language text? Because that's what AI users are hoping for.
> There are no lossless transformations of natural-language text
Of course there are. The article simply defines "transformation" such that it excludes the lossless ones. :-)
Ok but the idea is that you can throw in all your files a stream of consciousness barf and then get something readable that conveys the point better than you could have done with decades of practice. And the best systems would probe you at whatever meta level you stop caring about.
Another way this could go is that you simply don't need to communicate your ideas to another person anymore, that everyone hyper-specializes into their own language, if not just straight up the AI scanning your brain.
These are very well formulated rules about how to use an LLM to write documentation.
> Writing is thinking. Spending time on the writing process — on deciding what to emphasize and how to structure your ideas clearly — teaches you more about your topic. If you circumvent this process, you will probably walk away with a poorer understanding of the subject matter.
This is a point with which I completely agree.
It is extremely frequent that only when you write a detailed documentation for the product that you have designed, you finally understand some of its finer points, which perhaps need some last-minute changes, to prevent future problems.
Because of this, I despise the companies where the project plans do not allocate an adequate time for writing documentation, believing that this is some kind of unproductive activity. I have worked at many companies, in many countries, and without exception the best productivity, measured in the rate of completing projects that worked OK in production or at customers, was at the companies where the project schedules seemed to be more relaxed, by allocating a generous time for writing documentation.
Also when I was a child, much of what I did learn I learned by trying to explain those things to my schoolmates, and this was significantly more than I had learned directly from teachers.