more documentation/clarification of things