improve documentation

fixes #1391

and add improvements/fixes to documentation
I still don't get what are you trying to do here... why do you `store_objects` twice?