updated docs based on design
updated to show latest ideas from Victor