Improve documentation

[jfmengels]

Hi there 👋
I found a bunch of places where documentation could be improved.

• Some of the documentation was indented and was therefore presented as a code block
• Some of the code blocks were really long, and therefore you had to horizontally scroll to see the contents (it's still there now but it's a lot better)
• Changed the way ClauseInCase was presented to tell more like a story. This can be done for plenty of others as well I think.
• Applied elm-format to some of the files
• Fixed a few typos or errors, and did some tiny bit of cleanup of the code.

Let me know if you'd like this to be split into several PRs.