more clarification of shear documentation