improve documentation

fixes #1391

and add improvements/fixes to documentation
Same here.... in this specific case I think it *should* be ok as I copied and pasted the first sentence from http://bokeh.pydata.org/index.html  :-D

In any case I'm happy to change with something more "effective".