update reference doc and move some details there