update to the high level documentation

additional explanation and tiny bit of markdown to show angle brackets, plus a few spelling corrections and hopefully no introductions of same

/cc @snehaso