Some documentation fixups.

(while I was reading the docs…)

- Rephrased some of the things that weren't clear while reading them
- Put javascript hilighting whenever we had JSON
- don't use more that three spaces for code-blocks.