documentation: explanations and typo fix