Abhorrently bad take and misses the biggest reason that documentation usually is a second class citizen, and that is because your code is law, and code and tests are coupled, while documentation is not (thats why there is such huge push for autogeneration). Even code comments are considered a code smell because they are not part of CICD process. The way they describe documentation here reads more like a feature story and not being able to fully complete a spec, which is a tangential problem.
For LLM aspect - My take is the better approach is similar context enrichment for rag - you ask the LLM to generate a summary for a page, and that can easily be cached against a digest/hash for any code changes - and will always be up to date.
I think documentation and tests are and should be as coupled to the original code.
True that docs are not part of CI/CD and can get stale faster. Do you feel there is a huge push for autgeneration though?
> My take is the better approach is similar context enrichment for rag - you ask the LLM to generate a summary for a page,
Curios to hear more about. Are you referring to a doc's page?
They are both super important and complimentary, true. But if you could only do one? Which one would you choose?
I see your point with tests as examples, but I would find those pretty hard to read/find compared to docs. And if the doc's examples are not backed by tests we get into the same problem as docs being outdated.
Abhorrently bad take and misses the biggest reason that documentation usually is a second class citizen, and that is because your code is law, and code and tests are coupled, while documentation is not (thats why there is such huge push for autogeneration). Even code comments are considered a code smell because they are not part of CICD process. The way they describe documentation here reads more like a feature story and not being able to fully complete a spec, which is a tangential problem.
For LLM aspect - My take is the better approach is similar context enrichment for rag - you ask the LLM to generate a summary for a page, and that can easily be cached against a digest/hash for any code changes - and will always be up to date.
I think documentation and tests are and should be as coupled to the original code. True that docs are not part of CI/CD and can get stale faster. Do you feel there is a huge push for autgeneration though?
> My take is the better approach is similar context enrichment for rag - you ask the LLM to generate a summary for a page,
Curios to hear more about. Are you referring to a doc's page?
Tests and documentation are like peanut butter and jelly.
Tests can be examples of how to do things. If examples in your documentation aren't backed by unit tests they don't work.
They are both super important and complimentary, true. But if you could only do one? Which one would you choose?
I see your point with tests as examples, but I would find those pretty hard to read/find compared to docs. And if the doc's examples are not backed by tests we get into the same problem as docs being outdated.