I believe that thinking in these terms it the most complex way to design the documentation of something. Things should be built bottoms up, which is to start from what must be there and then thinking for whom all things should also be added.
For eg- Unix time irrespective of by whom or where is used, it remains universal and in need.
So, feature description with working code irrespective of kind of user is a must thing. Unity and some other engine follows the same approach. Our PG guide is better than them because you've added diagrams also.
Now, bring people:
1) Those who have never written a code must get there basics cleared. Or learn drag and drop engine! It's not engine developers to teach them programming or even game programming
2) Coding experience but not game!! You or anyone can explain this with a very basic game which teaches the general game cycle! And then game engine specific cycle..
I talked about 3 Unity games!! Level of difficultly was exactly this. 1st game taught me to write in Unity as well as Game engine cycle. Benefit? I was making a game along with it.
3) That's benefit for everything. They can also follow above kind of tutorials and learn Cocos engine life cycle first. Then they can always read documentations(extensive Programmers Guide)
4) Code is by itself well categorized. So, I dealing into dangerous part should be left on learner/developer itself in the starting phase.
5) That's should be part of code writer of that api to clearly write what that api is about!
6) advance under pinnings can be, for me, shaders, etc! We can always have advanced topics in extensive programmer's guide.
I'm telling you exactly how I learnt from poor programmer to understand Unity and how game development is done and then I picked Cocos2d-x
What's I think is, extensive programmer's guide should NOT be mixed with GAME! but feature description, EXACTLY like Unity Api Documentation but with diagrams.
Now, comes the good part where you can list tutorials, examples, use cases etc. in a separate section like Unity has.