It sure is hot in this thread. For me, the problem with the documentation, and most software documentation really, is not that the information would be missing, but rather that it is too difficult to find, and sometimes, when you have found it, you don’t realize you’re looking right at it.
I believe this question which testure just answered shows it quite well. I was looking for some kind of boolean property, instead I should have looked for enums; and then even after that, some creative thinking would be needed to connect the dots to understand what is meant by CAMERA there.
From my professional experience, a documentation won’t really shine unless it is accompanied by a guidebook. It wouldn’t explain every property of course, but you’d have all sorts of interconnected, bite-sized pages to explain key-concepts. Right now we have a quickstart and some lengthy module descriptions for everything under bpy, which make believe that all concepts can be understood in a 5-minute read. As soon as you want to do 1 thing more than the most basic hello triangle example, you’ll find more concepts that aren’t explained to you. You put on your detective’s coat, and off you go.
I am pretty sure we lack something in between the Blender reference manual and the Python API documentation. Something that helps to build a mental model of the abstractions which technicalities inevitably create, without having to worry about how to deal with it in Python. Then, the actual API documentation could blurt about technicalities with confidence to its heart’s content, because the reader already knows what they are looking for.