Fix and refactor large parts of the documentation

A couple of issues have been found on the documentation after re-reading
it related mainly to paging.
Fix typo in documentation