clarify some points in the documentation