clarify confusing docs