UI Draw Order

As my first post of this type, I think I should introduce my purpose. I find the Unity documentation quite lacking, I would say that much harsher but I forbear. I have been coding since I was 14 and am now 48. I have a long history of reading documentation from all the major players over the last 30 years. Instead of just being frustrated about Unity documentation I have decided to do something about it. I hope to make a post about everything I find difficult to understand, incomplete, or missing.

One major overall though first: Please combine the "manual" and the "scripting" documentation, ala the MSDN of the 90's. Great documentation, and included books on every facet of software design. Unity scripting (once improved) could be that great documentation and then the manual becomes a book on game design (allowing for additional books to be added that actually cover advanced game design issues).

First post:
This page:
http://docs.unity3d.com/Manual/UICanvas.html
Says:
"Draw order of elements

UI elements in the Canvas are drawn in the same order they appear in the Hierarchy. The first child is drawn first, the second child next, and so on. If two UI elements overlap, the later one will appear on top of the earlier one.

To change which element appear on top of other elements, simply reorder the elements in the Hierarchy by dragging them. The order can also be controlled from scripting by using these methods on the Transform component: SetAsFirstSibling, SetAsLastSibling, and SetSiblingIndex."

What that leaves out is the order that grandchild elements are drawn. I assume that child 1 (1.1) of child 1 (1) is drawn before child 2 (2) and all of child 2's children (2.1, 2.2, 2.3, etc). But further does SetSiblingIndex violate hierarchy order and allow me to set a grandchild of an earlier sibling to be drawn after a later sibling? Can I use SetSiblingIndex to have grandchild 1.1 draw after child 2? Does the index start with the first child (it does per the documentation) and then proceed to that child's children or to the next sibling in line? The documentation is unclear at best and the scripting documentation of SetSiblingIndex is a joke.

I hope these posts are well received and that it starts a community of people posting their improvements to the documentation.

 

No problem. I would think that corporate priorities would place documentation higher on the chain. Good documentation means more growth as less capable teams learn from your documentation and create games that compete with bigger houses and thus more game companies. Good documentation = more people paying for unity. Is this not obvious or are there other forces at play?

As for github/bitbucket, I wouldn't use a third party site for Unity property. I'm willing to contribute here but I'm less willing to create an account on yet another site... I have recently started using markdown due to Ember and Discourse, and there are pages I'd love to contribute to. It would be great to have a chance to overhaul Unity's entire documentation, as I recently starting developing with Unity, and have been coding for 30+ years I'm shocked at how incomplete Unity documentation is. I'm also shocked at the orientation or perspective it's talking from. I realize that you've geared it to two main audiences "designers" and "developers" but often feel that the part that should be talking to the developer has been written by a designer, and thus I have no idea how to do that in code.