Documentation overhaul

[jberkel]

The documentation hasn't been updated in a while, and new features have been added. We should go through the documentation and make sure it's still relevant, and that the code snippets compile, and that the playground still works.

Also add docs regarding error handling (failable vs. "normal" iterator)

#786, #583

Maybe it's also worth looking at closed tickets again to see what users struggle with, and make sure the documentation covers the frequent questions.