More verbose documentation

longer answer to why?