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 can't 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') isn't shown in the map - and not because it's just elsewhere on the map! Also notice how although note 'kk' is the next sibling to 'jj', it isn't 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 values and (since v5.0.1) also $OutlineOrder and $SiblingOrder. 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 aren't 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.
Be aware that the way adornments list in outline order changed from v5.0.0 onwards - their notional outline order used to be based on sibling order as at creation. Adornments created pre-v5.0.0 will continue to use the old $OutlineOrder placing. Thus in a long-lived TBX you may get both though this will likely only be apparent if you're inspecting $OutlineOrder or using adornment $OnAdd.
Next… What is SiblingOrder?