fix typos and code blocks, and some other clarification and refactoring

Signed-off-by: bowlofarugula <[email protected]>

Author: bowlofarugula