adding details and explaining "design-descisions"