I took a stab at updating the documentation: https://github.com/hibernate/hibernate-orm/pull/560
I hope it saves some developers some time.