Merge pull request #3551 from alcohol/minor-documentation-adjustments

WIP: rewriting some documentation sections