add technical documentation about ref iteration