Going into AI-assisted development, I thought this would be the winning strategy. I’ve since learned it’s not.

LLMs have a limited context window. It’s can’t hold a full moderately sized project in context, let alone the code of the referenced libraries. Some tools have documentation that exceed the context window.

So I’ve found that adding documentation and adding that to the context helps significantly. I even often let the AI tools generate my documentation where possible (and then manually edit). For me and the tools I use, this has helped significantly.

Code does not contain all the information of a feature.

Sometimes documentation is preferred source of truth, especially when multiple implementations exist. For example when you're writing code for POSIX API, you don't want to tie your code to glibc specific implementation, portable code is the whole point of POSIX.

Actually, programming languages are also for humans.

Think about it, what do you read when integrating APIs, code or documentation?

Code typically describes only the what and how. The why is usually left in people’s heads and, if you are lucky, in documentation.

Isn't code for humans as well then?