doc: update language and structure to add consistency

what's with all the indents? you don't need to indent when you do triple ```s