Update documentation: more notes about design considerations