more design docs updates