WIP: rewriting some documentation sections

Please leave feedback or suggestions
Maybe write: `Linux / OSX` instead of *nix and you can scrap the next line.