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