I've built an agent that builds documentation for code bases and you are 100% right. Having big picture documentation is important, but having bite size explanations about why some components work a certain way is more important. Making sure the AI doesn't have to infer behavior from code is really powerful. Even going as low level of reference docs. Even though devs would prefer that a method be self-Explanatory, it helps to also have plain english explanation about what's happening in a class or method.