added docs and thoughts