updating docs to be more expressive and useful