move some specs back into docs