The current List collection documentation could be improved by explicitly stating that the indices returned by the Insert method are not array-type sequential indices, but are more like handles.
The current statement "Inserting an item in the list at position index will cause the items in the list after position index to have their indexes modified by the list object." could be interpreted to mean that inserting an item at the head (for example) causes all subsequent indices to be incremented to maintain an array-like index. This is not the case.
list = .list~new
index = list~insert('first', .nil)
index = list~insert('second', .nil)
say 'by index:'
do j = 0 to list~items-1
say ' '
say 'by ordered iteration:'
do i over list
produces the output: