address most of @Eric89GXL points + improve docs