What is OutlineOrder?
It is a number value that indicates where, in the overall outline of the whole document, a note is to be placed. If you start a new outline and add 3 notes, they would have $OutlineOrder numbers 1, 2 and 3; the parent TBX document itself is always number 0 (zero). If you then dragged item 3 above item 2 and inspected $OutlineOrder (do this via Info view, General group) you would find old item 3 now has $OutlineOrder 2 - as it is new the second item in the outline. If you nest notes and expand all the nesting, the outline numbering runs from top-to-bottom - the descendants of top level item 1 all number before top level item 2, etc. $OutlineOrder is found in the General group of system attributes.
As the name implies $OutlineOrder does affect the outline. The attribute is read-only and cannot be changed directly via action code but alter $OutlineOrder by any other means and the outline ordering will change to reflect this. For instance, add a new note higher in the outline order and an all notes below will have their $OutlineOrder recalculated and increase by one. However, and importantly for this article, $OutlineOrder is not used for controlling placement of objects on a map view. That said, $OutlineOrder does have an affect on stacking/overlapping on maps but more on that later. The lower the $OutlineOrder, the higher up the outline view that item will be drawn.
Note that the outline's separator ('gg') is not shown in the map - and not because it is just elsewhere on the map. Also notice how although note 'kk' is the next sibling to 'jj', it is not the next in $OutlineOrder as all the descendants of 'jj' are numbered in between 'jj' and 'nn'.
Aliases have their own 'intrinsic' $Xpos/$Ypos/$Height/$Width/$OutlineOrder/$SiblingOrder values. Note how the alias of 'bb' is in a different map location and has a different size (but not $Shape) from its original note It also has its own number in the outline order.
In the outline part of the picture, notice the 'READ ME' note has an $OutlineOrder of #22, whereas the last item listed before it - the alias of 'dd' - is numbered #19. The missing numbers are the map adornments (#20 & #21), which of course are not visible in the outline. This is because adornments always list after all other items in the same container's map, i.e. including such items as separators.
Next… What is SiblingOrder?