readme better describes choices and tech debt