Comment by gonzalohm
15 hours ago
The spec will never be able to capture all the edge cases. The code is what runs. It also doesn't capture all the edge cases (that's why code has bugs) but it does a better job at that than documentation. Documentation can also become stale easily
This, and maintaining the spec is a cat-and-mouse game precisely to cover those edge cases.
Like "if you're using this database, and the engine has these configurations, then do _x_, unless _x'_ and _y'_ are enabled, in which case, do _y_..."
Which, if you're already being THAT specific in your spec, you might as well, idk, write the code yourself?
Because at that point your human language is basically the code and AI is the compiler. A non-deterministic one.
Regardless, your business stakeholders won't understand what's going on anyway (nor should they), so we're back at square zero.
(I wrote Technical and Functional Requirements Documents as a business analyst in college. What's happening now _for most situations_ is more or less the same thing.)
I mostly agree with you, but for “Documentation can also become stale easily” … historically I’d 100% agree with you—I often forgot to update separate documentation files, forgot to update comments on related functions, etc—but AI is so much better at automatically catching and fixing this without prompting than I ever was.
That's true, but it's also prone to over documenting. As an example, for some reason it always tries to include a diagram of the folder structure in the project. I think that's not really useful and it's something that changes so often it's not worth documenting