updated docs for #3, #4 and #5