Perhaps then we need a programming language with an expressive power equal to natural language? "Mergesort is used because we must avoid the worst case time complexity of Quicksort".
The best documentation is not only how something works, but why it works that way. The “how” can be rediscovered easily whereas the “why” is easily forgotten.
Writing documentation helps me understand the problem I’m trying to solve in a different way than just jumping into coding does. Both approaches are useful, and picking which one to start with is a gut call most of the time. But forcing myself to describe the problem in text sometimes helps.
Llms can explain what the code does but they are not so good at why, at least right now they don't have the context and they'll never have if we don't document the code...
IF we wrote the whys in the commit messages and the tickets. Maybe a good integration could provide all that context to the llm. That looks like a big if to me.
Whom can the reader ask for documentation? Perhaps the original author has gone, or forgotten. What if the thing was produced by many authors, and it's not now clear which one person can produce good documentation? Is it practical to convene a committee to answer the request?
Comments
Otherwise, absolutely