docs: consistent spacing around headings

Start out with 2 empty lines before/after for top level, decrease for deeper
levels.

docs: rework stuff

The existing docs were far from how we wanted it to be. There was so much to do
and it is not feasible to do that cleanup it in clean patches.

Instead, I took a sweep through the docs and changed what I thought could
benefit from a change: structure, examples, advices, language, markup, content,
etc.

more detailed logging on auth system
- docs updates for debugging
- code garden