WIP: rewriting some documentation sections

Please leave feedback or suggestions