clarified docs based on final design