Improve docs on error handling in Akka Streams

Opening this ticket after some feedback at a meetup. We should discuss the various ways of error / failure handling, this is separate to actually making supervision a good one ( https://github.com/akka/akka/issues/19950 ). People seem to be confused about the various options, and what would be considered idiomatic. I don't think we explain failure vs. "domain error" as well in the docs there. They could use a revamp.

E.g. we should discuss pros and cons of passing around Either/Xor instead of failing stages etc. Some examples would be good.

Also, note to self, the reason users were passing around Xors were that they wanted to report metrics about that in a centralised place (in one stage). This would have not been needed if we could monitor a stream for count of failures etc.