documentation: organize documentation outline better 

This moves the "Contents" close to the top if the index page, while moving some documentation pages around in the outline.

The actually text received only light editorial changes, mainly to fix section heading problems.

See #438 for more details.