My edits to the second half of the basic docs

cc @stubailo @avital @Slava
Yeah you have some good API ideas here, we should def implement them after 1.0