more clearly, improve a lot of unclear descriptions, add some missing material. We still need a migration guide though.
