update doc + add helpers