improved the documentation

@jacobawenger do you mind looking over the doc changes? thanks!
Let's end each sentence like this (aka ones that are followed with a code sample) with a colon (dopplepunkt?, for you German folk).