I have gotten use to Qt’s documentation and it comes closer to combining example sections with reference sections but it is still a struggle.
One documentation method that I used in the past was IBM’s Keyword In Context. The index of a manual gave all references to a word in manual used in specific contexts.
The manuals where usually structured in a recursive style of Introduction/Body/Technical Details.
When I wanted to look up something, I looked in the index for the keyword and go to references where that keyword was used in a particular context.
Made for very quick look ups.